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,
    "city": "Riyadh"
  },
  "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`) and optional `city` (English or Arabic label)
`location.city`	string	City name for vendor mapping (The Chefz resolves this to `city_id` on branch sync)
`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"

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,
    "city": "Riyadh"
  }
}

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), optional `city` (max 500 chars)

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, "city": "Riyadh" }
    },
    {
      "iv_id": "STORE-002",
      "name_en": "Mall Branch",
      "active": true,
      "location": { "lat": 24.7500, "lon": 46.7000, "city": "Riyadh" }
    }
  ]
}

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

Products

Products that exist at branches.

SKUs

Per-branch inventory records.

Branches

BranchesCopy Anchor Link

The Branch ObjectCopy Anchor Link

FieldsCopy Anchor Link

List BranchesCopy Anchor Link

Query ParametersCopy Anchor Link

Example RequestCopy Anchor Link

ResponseCopy Anchor Link

Get Single BranchCopy Anchor Link

Create BranchCopy Anchor Link

Request BodyCopy Anchor Link

Required FieldsCopy Anchor Link

Optional FieldsCopy Anchor Link

Response (201 Created)Copy Anchor Link

Update BranchCopy Anchor Link

ExampleCopy Anchor Link

Delete BranchCopy Anchor Link

Response (204 No Content)Copy Anchor Link

Working HoursCopy Anchor Link

Weekday Object (embedded in branch POST/PUT)Copy Anchor Link

Canonical Array (recommended)Copy Anchor Link

Standalone Working-Hours EndpointCopy Anchor Link

Bulk OperationsCopy Anchor Link

Request BodyCopy Anchor Link

ModesCopy Anchor Link

ResponseCopy Anchor Link

Error ResponsesCopy Anchor Link

404 Not FoundCopy Anchor Link

409 ConflictCopy Anchor Link

RelatedCopy Anchor Link

Products

SKUs

On this page

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

Related