Branches
Managing physical locations and their auto-generated SKU relationships
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) |
List Branches
GET /api/v1/branchesQuery 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/code/{ivId}| Parameter | Type | Description |
|---|---|---|
ivId | string | Branch's external ID (iv_id) |
Returns the full branch object.
Create Branch
POST /api/v1/branchesRequest 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/code/{ivId}Full replacement — include all fields you want to keep.
Example
curl -X PUT "https://linkit.works/api/v1/branches/code/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/code/{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.
Bulk Operations
POST /api/v1/branches/bulkRequest 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" }
}