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.

The Order Object

{
  "id": "r1234567890abcdef",
  "organization_id": "org_abc123",
  "source": "salla",
  "external_id": "SALLA-ORD-12345",
  "customer_name": "Ahmed Hassan",
  "customer_email": "ahmed@example.com",
  "customer_phone": "+966501234567",
  "products": [
    {
      "product_id": "prd_001",
      "name": "Panadol Extra",
      "quantity": 2,
      "price": 15.50,
      "total": 31.00
    }
  ],
  "subtotal": 31.00,
  "discount": 0,
  "tax": 4.65,
  "delivery_fee": 10.00,
  "total_amount": 45.65,
  "currency": "SAR",
  "status": "delivered",
  "payment_status": "paid",
  "fulfillment_status": "fulfilled",
  "notes": "",
  "created": "2024-01-15T10:30:00Z",
  "updated": "2024-01-16T14:22:00Z"
}

Key Fields

Field	Type	Description
`id`	string	Internal Linkit ID
`source`	string	Origin platform (e.g., `salla`, `hungerstation`, `manual`)
`external_id`	string	Order ID from the source platform
`products`	array	Line items with product details
`total_amount`	number	Final order total
`currency`	string	ISO 4217 currency code
`status`	string	Order status
`payment_status`	string	Payment state
`fulfillment_status`	string	Fulfillment state

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

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
`source`	string	-	Filter by source platform
`search`	string	-	Search in customer name, email, external ID
`created_from`	string	-	Orders after this date (ISO 8601)
`created_to`	string	-	Orders before this date (ISO 8601)
`sort`	string	-created	Sort field

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 orders = await response.json();

import requests

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

Response

{
  "data": [
    {
      "id": "r1234567890abcdef",
      "source": "salla",
      "external_id": "SALLA-ORD-12345",
      "customer_name": "Ahmed Hassan",
      "total_amount": 45.65,
      "currency": "SAR",
      "status": "delivered",
      "created": "2024-01-15T10:30:00Z"
    }
  ],
  "count": 25,
  "total_count": 5432,
  "page": 1,
  "limit": 50,
  "has_next": true,
  "meta": {}
}

Get Single Order

GET /api/v1/orders/{id}

Returns the full order object with all line items, customer details, and status history.

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)

{
  "id": "r1234567890abcdef",
  "source": "manual",
  "status": "pending",
  "total_amount": 83.98,
  "created": "2024-01-15T10:30:00Z"
}

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" }
}

Products

Product catalog for order line items.

Customers

Customer profiles linked to orders.

Bulk Operations

High-volume order processing.

Orders

Products

Customers

Bulk Operations

On this page