Skip to main content
POST
Link Store to Employee
This endpoint creates employee relationships between a new employee and multiple stores in a single operation. It’s particularly useful for multi-store employees, area managers, or support staff who need access to multiple store locations.

Request Body

array
required
Array of store IDs to link the employee toExample: [“b2b56ffb-e198-49f3-a1bc-f36ac70f9501”, “d7c17a59-01e1-48f2-a326-2bbd3c888205”]
string
required
The unique employee identifier (UUID format) for this employeeExample: “30523fd1-e108-41d0-a02d-f5907336f2e4”
number
required
The company ID that owns the stores being linkedExample: 1000022
number
required
The user ID of the employee being linked to storesExample: 1000305

Request Example

Response

number
Number of stores successfully linked to the employee
Array of successfully created store-employee relationships
Array of stores that failed to link with error details

Response Example

Multi-Store Employee Types

role
Manages operations across multiple store locations
Typically needs manager-level access to all assigned stores
role
Oversees store performance and compliance across a region
May need administrative access for reporting and auditing
role
Works at different stores as needed for coverage
Usually assigned basic employee access to maintain flexibility
role
Provides technical or operational support across multiple locations
Access should be limited to specific functions they support
role
Conducts training programs at multiple store locations
May need temporary elevated access for training purposes

Batch Operation Benefits

benefit
Create multiple employee relationships in a single API call
Reduces API calls and improves performance
benefit
Ensures consistent access levels across all linked stores
Reduces configuration errors and access inconsistencies
benefit
Either all stores link successfully or the operation fails safely
Prevents partial failures that could cause access issues
benefit
Creates comprehensive audit log for multi-store employee setup
Important for compliance and security tracking

Validation and Error Handling

validation
All store_ids must belong to the specified company_id
Cross-company linking is not permitted for security
validation
All stores must be active and accessible to the requesting user
Inactive or restricted stores will be skipped
validation
Employee ID must be unique across the system
Prevents conflicts and ensures proper identification
validation
User ID must correspond to an existing, active user
Verify user exists before attempting multi-store linking

Use Cases

use-case
Set up area managers or regional supervisors with access to multiple stores
Common during leadership team expansion
use-case
Create flexible staff assignments for busy periods
Allows employees to work at multiple locations as needed
use-case
Grant technical or operational support teams access to multiple stores
Useful for maintenance, training, or technical support roles
use-case
Set up franchise owners or operators with access to all their locations
Ensure proper authorization for franchise relationships

Error Recovery

Check failed_links array to identify stores that didn’t link successfully
Common failures include inactive stores or permission issues
recovery
Use single-store linking endpoint for failed stores after resolving issues
May require different access levels or additional permissions
Confirm that successful links provide the expected access
Test access to ensure employee can perform required functions
Partial Success Handling: This endpoint can succeed partially - some stores may link successfully while others fail. Always check both the count and failed_links array.
Company Security: All stores must belong to the same company for security reasons. Cross-company employee access requires separate authorization processes.
Performance Consideration: While efficient for multiple stores, very large store lists may take longer to process. Consider batching for extremely large operations.