Link Store to Employee

This endpoint links multiple stores to a new employee, creating employee relationships across multiple store locations simultaneously. This is useful for employees who work across multiple stores or for managers overseeing multiple locations.

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

store_ids · array · required

Array of store IDs to link the employee to

Example: [“b2b56ffb-e198-49f3-a1bc-f36ac70f9501”, “d7c17a59-01e1-48f2-a326-2bbd3c888205”]

employee_id · string · required

The unique employee identifier (UUID format) for this employee

Example: “30523fd1-e108-41d0-a02d-f5907336f2e4”

company_id · number · required

The company ID that owns the stores being linked

Example: 1000022

user_id · number · required

The user ID of the employee being linked to stores

Example: 1000305

Request Example

{
    "store_ids": [
        "b2b56ffb-e198-49f3-a1bc-f36ac70f9501",
        "d7c17a59-01e1-48f2-a326-2bbd3c888205",
        "449235c1-3d04-4519-998b-40d2a621e5e0"
    ],
    "employee_id": "30523fd1-e108-41d0-a02d-f5907336f2e4",
    "company_id": 1000022,
    "user_id": 1000305
}

Response

count · number

Number of stores successfully linked to the employee

successful_links · array

Array of successfully created store-employee relationships

Show Link Details

store_id · string

Store ID that was successfully linked

employee_id · string

Employee ID used for the link

access_level · string

Access level granted for this store

linked_at · string

When the link was created

failed_links · array

Array of stores that failed to link with error details

Show Failed Link Details

store_id · string

Store ID that failed to link

error · string

Reason for the failure

error_code · string

Error code for programmatic handling

Response Example

{
    "count": 2,
    "successful_links": [
        {
            "store_id": "b2b56ffb-e198-49f3-a1bc-f36ac70f9501",
            "employee_id": "30523fd1-e108-41d0-a02d-f5907336f2e4",
            "access_level": "store_employee",
            "linked_at": "2024-11-15T10:30:00.000Z"
        },
        {
            "store_id": "d7c17a59-01e1-48f2-a326-2bbd3c888205",
            "employee_id": "30523fd1-e108-41d0-a02d-f5907336f2e4",
            "access_level": "store_employee",
            "linked_at": "2024-11-15T10:30:01.000Z"
        }
    ],
    "failed_links": [
        {
            "store_id": "449235c1-3d04-4519-998b-40d2a621e5e0",
            "error": "Store not found or not accessible",
            "error_code": "STORE_NOT_FOUND"
        }
    ]
}

Multi-Store Employee Types

Common Multi-Store Employee Roles

Area Manager · role

Manages operations across multiple store locations

Typically needs manager-level access to all assigned stores

Regional Supervisor · role

Oversees store performance and compliance across a region

May need administrative access for reporting and auditing

Floating Employee · role

Works at different stores as needed for coverage

Usually assigned basic employee access to maintain flexibility

Support Specialist · role

Provides technical or operational support across multiple locations

Access should be limited to specific functions they support

Trainer · role

Conducts training programs at multiple store locations

May need temporary elevated access for training purposes

Batch Operation Benefits

Advantages of Multi-Store Linking

Efficiency · benefit

Create multiple employee relationships in a single API call

Reduces API calls and improves performance

Consistency · benefit

Ensures consistent access levels across all linked stores

Reduces configuration errors and access inconsistencies

Atomic Operations · benefit

Either all stores link successfully or the operation fails safely

Prevents partial failures that could cause access issues

Audit Trail · benefit

Creates comprehensive audit log for multi-store employee setup

Important for compliance and security tracking

Validation and Error Handling

Operation Validation

Company Ownership · validation

All store_ids must belong to the specified company_id

Cross-company linking is not permitted for security

Store Accessibility · validation

All stores must be active and accessible to the requesting user

Inactive or restricted stores will be skipped

Employee ID Uniqueness · validation

Employee ID must be unique across the system

Prevents conflicts and ensures proper identification

User Existence · validation

User ID must correspond to an existing, active user

Verify user exists before attempting multi-store linking

Use Cases

When to Use This Endpoint

New Manager Onboarding · use-case

Set up area managers or regional supervisors with access to multiple stores

Common during leadership team expansion

Seasonal Staffing · use-case

Create flexible staff assignments for busy periods

Allows employees to work at multiple locations as needed

Support Team Setup · use-case

Grant technical or operational support teams access to multiple stores

Useful for maintenance, training, or technical support roles

Franchise Operations · use-case

Set up franchise owners or operators with access to all their locations

Ensure proper authorization for franchise relationships

Error Recovery

Handling Partial Failures

Review Failed Links · recovery

Check failed_links array to identify stores that didn’t link successfully

Common failures include inactive stores or permission issues

Retry Individual Stores · recovery

Use single-store linking endpoint for failed stores after resolving issues

May require different access levels or additional permissions

Verify Successful Links · recovery

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.