Orders

Orders are ingested from any source — manual entry, integrations, or API calls. Each order tracks customer info, line items, totals, status, and fulfillment data.

Read responses (GET /api/v1/orders, GET /api/v1/orders/{id}) always use a single contract: an envelope with spec_version 2026-04-01, event metadata, and a normalized order object (UnifiedOrderPayload). Vendor-native capture may still be stored server-side for ingestion; it is not returned in JSON.

UnifiedOrderPayload (`order` field)

This is the normalized order inside every read envelope. Field names mirror outbound webhooks.

Field	Type	Description
`id`	string	Order record id
`organization_id`	string	Tenant id
`source_reference`	string	Human or upstream reference
`source_transaction_id`	string	Idempotency / upstream transaction key
`source_timestamp`	string	Provider timestamp (RFC3339), when known
`destination_id`	string	Branch / store id in Linkit
`destination_reference`	string	External branch or vendor reference
`order_status`	string	Workflow status
`fulfillment_status`	string	Fulfillment pipeline
`payment_status`	string	Payment pipeline
`fulfillment_method`	string	e.g. `delivery`, `pickup`, `shipping`
`payment_method`	string	Tender / channel
`currency`	string	ISO 4217
`total_amount`	number	Grand total
`discounts_amount`	number	Discounts
`vat_amount`	number	VAT
`customer_name` / `customer_phone` / `customer_email`	string	Buyer
`receiver_name` / `receiver_phone`	string	Recipient when different
`skus`	string[]	Sku codes when normalized
`products`	array	Line items (normalized JSON)
`shipping_address`	object	Structured address when present
`order_code`	string	Display code
`order_type`	string	Order classification
`transport_type`	string	Logistics / handoff hint
`comment`	string	Notes
`promised_for`	string	Scheduled / promise time (RFC3339)
`is_preorder`	boolean	Preorder flag
`delivery_fee` / `service_fee` / `subtotal`	number	Fee breakdown
`store_name`	string	Resolved store label
`dispatch_routing`	object	Dispatch metadata when present
`shipping_fulfillment`	object	Carrier / fulfillment metadata when present
`created_at` / `updated_at`	string	Linkit record times (RFC3339)

organization_app_id and catalog app_slug live on the parent envelope (see below), not on order — orders.source in storage is the install id (organization_apps row).

Order Statuses

Status	Description
`pending`	Received, not yet processed
`confirmed`	Accepted by the merchant
`preparing`	Being prepared
`ready`	Ready for pickup or delivery
`shipped`	In transit
`delivered`	Successfully delivered
`cancelled`	Cancelled before fulfillment
`returned`	Returned after delivery

Payment Statuses

Status	Description
`pending`	Awaiting payment
`paid`	Payment received
`refunded`	Full refund issued
`partially_refunded`	Partial refund issued
`failed`	Payment failed

List Orders

GET /api/v1/orders

Every call uses the same authenticated tenant context as the rest of the API: a valid bearer token plus the organization resolved from that token (or an X-Organization-ID override when your account is allowed to access that organization). No additional scopes apply beyond your existing membership and API key rules.

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	20	Items per page (max 100)
`status`	string	-	Filter by order status
`payment_status`	string	-	Filter by payment status
`fulfillment_status`	string	-	Filter by fulfillment status
`source`	string	-	Filter by source platform
`search`	string	-	Search in customer name, email, external ID
`from`	string	-	Lower bound on `created` (RFC 3339), e.g. `2026-04-21T00:00:00Z`
`to`	string	-	Upper bound on `created` (RFC 3339); omit for “until now”
`sort`	string	-created	Sort field

High-frequency polling (rolling window)

For terminals or integrations that poll every minute or so, narrow what you ask for: keep sort=-created, leave filters empty except pagination, and pass a from timestamp within roughly the last six hours (RFC 3339). Optional to should not be earlier than from. Under those conditions the service may answer directly from a tenant-isolated materialized view that is kept in lockstep whenever orders are created, updated, or removed for that organization—including when marketplace “orders” integrations promote rows from their intake feed into the unified order ledger.

When that path applies, the JSON body is still the same orders.listed list envelope as the database-backed path; only latency and backend routing differ.

Example Request

curl -X GET "https://linkit.works/api/v1/orders?status=delivered&source=salla&limit=50" \
  -H "Authorization: Bearer your_token_here"

const response = await fetch(
  'https://linkit.works/api/v1/orders?status=delivered&source=salla&limit=50',
  { headers: { 'Authorization': 'Bearer your_token_here' } }
);
const body = await response.json();
// body.event_type === "orders.listed"; body.orders[].event_type === "order.snapshot"

import requests

response = requests.get(
    'https://linkit.works/api/v1/orders',
    params={'status': 'delivered', 'source': 'salla', 'limit': 50},
    headers={'Authorization': 'Bearer your_token_here'}
)
body = response.json()

Response

{
  "spec_version": "2026-04-01",
  "event_type": "orders.listed",
  "occurred_at": "2026-04-21T10:30:00.123456789Z",
  "organization_id": "org_abc123",
  "orders": [
    {
      "spec_version": "2026-04-01",
      "event_id": "snapshot-r1234567890abcdef-1713694200123456789",
      "event_type": "order.snapshot",
      "occurred_at": "2026-04-21T10:30:00.123456789Z",
      "organization_id": "org_abc123",
      "organization_app_id": "org_app_install_row_id",
      "app_slug": "salla-orders",
      "order": {
        "id": "r1234567890abcdef",
        "organization_id": "org_abc123",
        "source_reference": "SALLA-ORD-12345",
        "source_transaction_id": "TXN-001",
        "source_timestamp": "2026-04-21T09:00:00Z",
        "destination_id": "store_iv_1",
        "destination_reference": "REF-001",
        "order_status": "RECEIVED",
        "fulfillment_status": "Full",
        "payment_status": "paid",
        "fulfillment_method": "delivery",
        "payment_method": "card",
        "currency": "SAR",
        "total_amount": 45.65,
        "discounts_amount": 0,
        "vat_amount": 0,
        "customer_name": "Ahmed Hassan",
        "products": [],
        "created_at": "2026-04-21T09:05:00Z",
        "updated_at": "2026-04-21T10:00:00Z"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total_items": 5432,
    "total_pages": 109,
    "has_next": true,
    "has_prev": false
  },
  "meta": {}
}

Get Single Order

GET /api/v1/orders/{id}

Uses the same authenticated organization scope as list orders. The body is always one UnifiedOrderEventPayload with event_type order.snapshot (same order object as list rows). Cached hot reads return the same shape.

Example (trimmed)

{
  "spec_version": "2026-04-01",
  "event_id": "snapshot-r1234567890abcdef-1713694200123456789",
  "event_type": "order.snapshot",
  "occurred_at": "2026-04-21T10:30:00.123456789Z",
  "organization_id": "org_abc123",
  "organization_app_id": "org_app_install_row_id",
  "app_slug": "salla-orders",
  "order": {
    "id": "r1234567890abcdef",
    "source_reference": "SALLA-ORD-12345",
    "source_transaction_id": "TXN-001",
    "total_amount": 45.65,
    "currency": "SAR",
    "order_status": "RECEIVED",
    "products": []
  }
}

Create Order

POST /api/v1/orders

Request Body

{
  "source": "manual",
  "customer_name": "Sarah Smith",
  "customer_email": "sarah@example.com",
  "customer_phone": "+966509876543",
  "products": [
    {
      "product_id": "prd_001",
      "name": "Product One",
      "quantity": 2,
      "price": 29.99
    }
  ],
  "subtotal": 59.98,
  "tax": 9.00,
  "delivery_fee": 15.00,
  "total_amount": 83.98,
  "currency": "SAR",
  "status": "pending",
  "payment_status": "pending"
}

Required Fields

Field	Type	Constraints
`source`	string	Origin identifier
`products`	array	At least one line item
`total_amount`	number	>= 0
`currency`	string	ISO 4217 code

Response (201 Created)

{
  "success": true,
  "message": "Order created successfully",
  "timestamp": "2026-04-21T10:30:00Z",
  "data": {
    "id": "r1234567890abcdef",
    "order_number": "ORD-2026-001"
  }
}

Update Order

PUT /api/v1/orders/{id}

Full replacement update. Include all fields you want to keep.

Update Order Status

Partial update for status fields only.

PATCH /api/v1/orders/{id}/status

Request Body

{
  "status": "delivered",
  "payment_status": "paid",
  "fulfillment_status": "fulfilled"
}

All fields are optional — include only the statuses you want to change.

Example

curl -X PATCH "https://linkit.works/api/v1/orders/r1234567890abcdef/status" \
  -H "Authorization: Bearer your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"status": "delivered", "payment_status": "paid"}'

Bulk Operations

Bulk Create

POST /api/v1/orders/bulk

Request body is an array of order objects (same structure as single create). Max 1,000 per request.

Bulk Status Update

PATCH /api/v1/orders/bulk/status

{
  "updates": [
    { "id": "order_001", "status": "delivered", "payment_status": "paid" },
    { "id": "order_002", "status": "cancelled" }
  ]
}

Bulk Delete

DELETE /api/v1/orders/bulk

{
  "ids": ["order_001", "order_002", "order_003"]
}

Response (all bulk operations)

{
  "success": true,
  "data": {
    "succeeded": 98,
    "failed": 2,
    "errors": {
      "order_050": "Order not found",
      "order_075": "Invalid status transition"
    }
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

Error Responses

404 Not Found

{
  "code": 404,
  "error": "Order not found",
  "details": { "id": "nonexistent" }
}

422 Validation Error

{
  "code": 422,
  "error": "Validation failed",
  "details": { "products": "At least one product is required" }
}

Orders

Orders

UnifiedOrderPayload (`order` field)

Order Statuses

Payment Statuses

List Orders

Query Parameters

High-frequency polling (rolling window)

Example Request

Response

Get Single Order

Example (trimmed)

Create Order

Request Body

Required Fields

Response (201 Created)

Update Order

Update Order Status

Request Body

Example

Bulk Operations

Bulk Create

Bulk Status Update

Bulk Delete

Response (all bulk operations)

Error Responses

404 Not Found

422 Validation Error

Products

Customers

Bulk Operations

On this page