Request Body
Array of store IDs to link the employee toExample: [“b2b56ffb-e198-49f3-a1bc-f36ac70f9501”, “d7c17a59-01e1-48f2-a326-2bbd3c888205”]
The unique employee identifier (UUID format) for this employeeExample: “30523fd1-e108-41d0-a02d-f5907336f2e4”
The company ID that owns the stores being linkedExample: 1000022
The user ID of the employee being linked to storesExample: 1000305
Request Example
Response
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
Common Multi-Store Employee Roles
Common Multi-Store Employee Roles
Manages operations across multiple store locations
Typically needs manager-level access to all assigned stores
Oversees store performance and compliance across a region
May need administrative access for reporting and auditing
Works at different stores as needed for coverage
Usually assigned basic employee access to maintain flexibility
Provides technical or operational support across multiple locations
Access should be limited to specific functions they support
Conducts training programs at multiple store locations
May need temporary elevated access for training purposes
Batch Operation Benefits
Advantages of Multi-Store Linking
Advantages of Multi-Store Linking
Create multiple employee relationships in a single API call
Reduces API calls and improves performance
Ensures consistent access levels across all linked stores
Reduces configuration errors and access inconsistencies
Either all stores link successfully or the operation fails safely
Prevents partial failures that could cause access issues
Creates comprehensive audit log for multi-store employee setup
Important for compliance and security tracking
Validation and Error Handling
Operation Validation
Operation Validation
All store_ids must belong to the specified company_id
Cross-company linking is not permitted for security
All stores must be active and accessible to the requesting user
Inactive or restricted stores will be skipped
Employee ID must be unique across the system
Prevents conflicts and ensures proper identification
User ID must correspond to an existing, active user
Verify user exists before attempting multi-store linking
Use Cases
When to Use This Endpoint
When to Use This Endpoint
Set up area managers or regional supervisors with access to multiple stores
Common during leadership team expansion
Create flexible staff assignments for busy periods
Allows employees to work at multiple locations as needed
Grant technical or operational support teams access to multiple stores
Useful for maintenance, training, or technical support roles
Set up franchise owners or operators with access to all their locations
Ensure proper authorization for franchise relationships
Error Recovery
Handling Partial Failures
Handling Partial Failures
Check failed_links array to identify stores that didn’t link successfully
Common failures include inactive stores or permission issues
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.