Branches

Branches represent physical locations — stores, warehouses, or distribution points. When you create a branch, Linkit auto-generates one SKU for every existing product at that branch. This product × branch matrix is the foundation of your inventory system.

The Branch Object

{
  "id": "r1234567890abcdef",
  "iv_id": "STORE-001",
  "organization_id": "org_abc123",
  "name_en": "Main Store - Riyadh",
  "name_ar": "المتجر الرئيسي - الرياض",
  "active": true,
  "location": {
    "lat": 24.7136,
    "lon": 46.6753
  },
  "created": "2024-01-15T10:30:00Z",
  "updated": "2024-01-16T14:22:00Z"
}

Fields

Field	Type	Description
`id`	string	Internal Linkit ID (auto-generated)
`iv_id`	string	Your external identifier for this branch
`name_en`	string	Branch name in English
`name_ar`	string	Branch name in Arabic
`active`	boolean	Whether the branch is operational
`location`	object	GPS coordinates (`lat`, `lon`)
`working_hours`	object or array	Legacy weekday object and/or canonical period list (see Working Hours below)
`working_hours_periods`	array	Normalized periods returned by the API (`WeekDay`, `OpenHour`, `OpenMinute`, `CloseHour`, `CloseMinute`)

List Branches

GET /api/v1/branches

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	20	Items per page (max 100)
`search`	string	-	Search in branch names
`active`	boolean	-	Filter by active status

Example Request

curl -X GET "https://linkit.works/api/v1/branches?active=true&limit=50" \
  -H "Authorization: Bearer your_token_here"

const response = await fetch(
  'https://linkit.works/api/v1/branches?active=true&limit=50',
  { headers: { 'Authorization': 'Bearer your_token_here' } }
);
const branches = await response.json();

import requests

response = requests.get(
    'https://linkit.works/api/v1/branches',
    params={'active': True, 'limit': 50},
    headers={'Authorization': 'Bearer your_token_here'}
)
branches = response.json()

Response

{
  "data": [
    {
      "id": "r1234567890abcdef",
      "iv_id": "STORE-001",
      "name_en": "Main Store - Riyadh",
      "name_ar": "المتجر الرئيسي - الرياض",
      "active": true,
      "created": "2024-01-15T10:30:00Z"
    }
  ],
  "count": 10,
  "total_count": 25,
  "page": 1,
  "limit": 50,
  "has_next": false,
  "meta": {}
}

Get Single Branch

GET /api/v1/branches/{ivId}

Parameter	Type	Description
`ivId`	string	Branch's external ID (`iv_id`)

Returns the full branch object.

Create Branch

POST /api/v1/branches

POST /api/v1/branches and PUT /api/v1/branches/{'{ivId}'} accept both application/json and multipart/form-data. Use multipart only when uploading images.

Request Body

{
  "iv_id": "STORE-NEW",
  "name_en": "New Branch",
  "name_ar": "فرع جديد",
  "active": true,
  "location": {
    "lat": 24.7136,
    "lon": 46.6753
  }
}

Required Fields

Field	Type	Constraints
`iv_id`	string	Max 50 chars, unique per organization

Optional Fields

Field	Type	Constraints
`name_en`	string	Max 255 chars
`name_ar`	string	Max 255 chars
`active`	boolean	Default: true
`location`	object	`lat` (-90 to 90), `lon` (-180 to 180)

Creating a branch triggers automatic SKU generation for every existing product. If you have 1,000 products, a new branch creates 1,000 SKUs.

Response (201 Created)

{
  "success": true,
  "message": "Branch created successfully",
  "data": {
    "id": "r1234567890abcdef",
    "iv_id": "STORE-NEW",
    "skus_generated": 1500
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

Update Branch

PUT /api/v1/branches/{ivId}

Full replacement — include all fields you want to keep.

Example

curl -X PUT "https://linkit.works/api/v1/branches/STORE-001" \
  -H "Authorization: Bearer your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "iv_id": "STORE-001",
    "name_en": "Main Store (Renovated)",
    "name_ar": "المتجر الرئيسي (مجدد)",
    "active": true
  }'

Delete Branch

DELETE /api/v1/branches/{ivId}

Parameter	Type	Default	Description
`force`	boolean	false	Delete even if the branch has associated SKUs

Deletion behavior

By default, branches with associated SKUs cannot be deleted. Use force=true to also delete all SKUs at this branch.

Response (204 No Content)

Success returns no body.

Working Hours

working_hours now supports two payload styles:

Weekday object (legacy-friendly)
Canonical multi-period array (recommended, supports split/overnight windows)

Weekday Object (embedded in branch POST/PUT)

{
  "working_hours": {
    "monday": { "open": "09:00", "close": "18:00" },
    "friday": {
      "periods": [
        { "open": "12:30", "close": "16:45" },
        { "open": "21:00", "close": "01:45" }
      ]
    },
    "saturday": { "closed": true }
  }
}

Canonical Array (recommended)

{
  "working_hours": [
    { "WeekDay": "Sunday", "OpenHour": 10, "OpenMinute": 0, "CloseHour": 16, "CloseMinute": 45 },
    { "WeekDay": "Sunday", "OpenHour": 20, "OpenMinute": 30, "CloseHour": 3, "CloseMinute": 15 },
    { "WeekDay": "Friday", "OpenHour": 12, "OpenMinute": 30, "CloseHour": 16, "CloseMinute": 45 }
  ]
}

Standalone Working-Hours Endpoint

PUT /api/v1/branches/{ivId}/working-hours

curl -X PUT "https://linkit.works/api/v1/branches/STORE-001/working-hours" \
  -H "Authorization: Bearer your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "working_hours": [
      {"WeekDay":"Sunday","OpenHour":10,"OpenMinute":0,"CloseHour":16,"CloseMinute":45},
      {"WeekDay":"Sunday","OpenHour":20,"OpenMinute":30,"CloseHour":3,"CloseMinute":15}
    ]
  }'

Bulk Operations

POST /api/v1/branches/bulk

Request Body

{
  "mode": "upsert",
  "branches": [
    {
      "iv_id": "STORE-001",
      "name_en": "Main Store",
      "active": true,
      "location": { "lat": 24.7136, "lon": 46.6753 }
    },
    {
      "iv_id": "STORE-002",
      "name_en": "Mall Branch",
      "active": true,
      "location": { "lat": 24.7500, "lon": 46.7000 }
    }
  ]
}

Modes

Mode	Behavior
`create`	Insert only — fails if branch exists
`update`	Update only — fails if branch not found
`upsert`	Create or update as appropriate

Response

{
  "success": true,
  "message": "Processed 50 branches successfully",
  "data": {
    "succeeded": 50,
    "failed": 0,
    "errors": {}
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

Error Responses

404 Not Found

{
  "code": 404,
  "error": "Branch not found",
  "details": { "iv_id": "NONEXISTENT" }
}

409 Conflict

{
  "code": 409,
  "error": "Branch with this iv_id already exists",
  "details": { "iv_id": "STORE-001" }
}

Branches

Branches

The Branch Object

Fields

List Branches

Query Parameters

Example Request

Response

Get Single Branch

Create Branch

Request Body

Required Fields

Optional Fields

Response (201 Created)

Update Branch

Example

Delete Branch

Response (204 No Content)

Working Hours

Weekday Object (embedded in branch POST/PUT)

Canonical Array (recommended)

Standalone Working-Hours Endpoint

Bulk Operations

Request Body

Modes

Response

Error Responses

404 Not Found

409 Conflict

Products

SKUs

Bulk Operations

On this page