> ## Documentation Index
> Fetch the complete documentation index at: https://developer.lulacommerce.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Link User to Store

> This endpoint links an existing user to a specific store, establishing their employee relationship and access permissions. This is used to assign employees to stores and grant them appropriate access levels for store operations.

This endpoint creates an employee relationship between an existing user and a store. It's essential for managing store staff access and ensuring employees have the proper permissions to operate within their assigned stores.

### Path Parameters

<ParamField path="store_id" type="string" required>
  The unique identifier of the store to link the user to
</ParamField>

### Request Body

<ParamField body="user_id" type="number" required>
  The ID of the existing user to link to the store

  Example: 1000049
</ParamField>

<ParamField body="employee_id" type="string" required>
  The unique employee identifier (UUID format) for this user-store relationship

  Example: "870a05c1-bbbf-48ab-a757-e28ae0a2b2a8"
</ParamField>

### Request Example

```json theme={null}
{
    "user_id": 1000049,
    "employee_id": "870a05c1-bbbf-48ab-a757-e28ae0a2b2a8"
}
```

### Response

<ResponseField name="success" type="boolean">
  Indicates whether the user was successfully linked to the store
</ResponseField>

<ResponseField name="employee_relationship" type="object">
  Details of the created employee relationship

  <Expandable title="Employee Relationship Object">
    <ResponseField name="store_id" type="string">
      The store ID the user is now linked to
    </ResponseField>

    <ResponseField name="user_id" type="number">
      The user ID that was linked
    </ResponseField>

    <ResponseField name="employee_id" type="string">
      The employee identifier for this relationship
    </ResponseField>

    <ResponseField name="access_level" type="string">
      Access level granted to the employee
    </ResponseField>

    <ResponseField name="linked_at" type="string">
      When the link was created (ISO 8601 format)
    </ResponseField>

    <ResponseField name="linked_by" type="string">
      User ID of who created this link
    </ResponseField>
  </Expandable>
</ResponseField>

### Response Example

```json theme={null}
{
    "success": true,
    "employee_relationship": {
        "store_id": "7669f473-6c40-45ee-8737-43c667407b3a",
        "user_id": 1000049,
        "employee_id": "870a05c1-bbbf-48ab-a757-e28ae0a2b2a8",
        "access_level": "store_employee",
        "linked_at": "2024-11-15T10:30:00.000Z",
        "linked_by": "1000001"
    }
}
```

### Employee Access Levels

<Accordion title="Available Access Levels">
  <ResponseField name="store_employee" type="access-level">
    Basic store employee access - can process orders and manage inventory

    <Info>Standard access for front-line employees</Info>
  </ResponseField>

  <ResponseField name="store_manager" type="access-level">
    Store manager access - can manage employees and store settings

    <Note>Elevated access for store management personnel</Note>
  </ResponseField>

  <ResponseField name="store_admin" type="access-level">
    Administrative access - full control over store operations

    <Warning>High-level access should be granted carefully</Warning>
  </ResponseField>

  <ResponseField name="limited_access" type="access-level">
    Restricted access for specific functions only

    <Tip>Useful for part-time or specialized roles</Tip>
  </ResponseField>
</Accordion>

### Prerequisites

<Accordion title="Before Linking Users">
  <ResponseField name="User Exists" type="prerequisite">
    The user\_id must correspond to an existing user in the system

    <Note>Users must be created before they can be linked to stores</Note>
  </ResponseField>

  <ResponseField name="Employee ID Valid" type="prerequisite">
    The employee\_id should be a valid UUID format

    <Warning>Invalid UUID formats will be rejected</Warning>
  </ResponseField>

  <ResponseField name="Store Active" type="prerequisite">
    The target store should be active and properly configured

    <Info>Linking to inactive stores may cause access issues</Info>
  </ResponseField>

  <ResponseField name="Permission Check" type="prerequisite">
    Requesting user must have permission to manage store employees

    <Note>Typically requires store manager or admin level access</Note>
  </ResponseField>
</Accordion>

### Post-Linking Effects

<Accordion title="What Happens After Linking">
  <ResponseField name="Access Granted" type="effect">
    User gains access to store-specific functions and data

    <Info>Access is immediate upon successful linking</Info>
  </ResponseField>

  <ResponseField name="Role Assignment" type="effect">
    User is assigned appropriate role-based permissions

    <Note>Permissions are based on the assigned access level</Note>
  </ResponseField>

  <ResponseField name="Audit Trail" type="effect">
    Employee relationship is logged for compliance and tracking

    <Tip>All employee changes are tracked for security purposes</Tip>
  </ResponseField>

  <ResponseField name="System Integration" type="effect">
    User appears in store employee lists and management interfaces

    <Info>Integration with POS and management systems is automatic</Info>
  </ResponseField>
</Accordion>

### Use Cases

<Accordion title="When to Use This Endpoint">
  <ResponseField name="New Employee Onboarding" type="use-case">
    Link new hires to their assigned store locations

    <Note>Part of the standard employee onboarding process</Note>
  </ResponseField>

  <ResponseField name="Employee Transfer" type="use-case">
    Move existing employees between store locations

    <Tip>May require unlinking from previous store first</Tip>
  </ResponseField>

  <ResponseField name="Temporary Assignment" type="use-case">
    Assign employees to stores for temporary coverage

    <Info>Can be reversed when temporary assignment ends</Info>
  </ResponseField>

  <ResponseField name="Access Management" type="use-case">
    Grant specific users access to store operations

    <Warning>Ensure access levels match job responsibilities</Warning>
  </ResponseField>
</Accordion>

### Error Scenarios

<Accordion title="Common Linking Errors">
  <ResponseField name="User Not Found" type="error">
    The specified user\_id doesn't exist

    **Status Code:** 404

    **Solution:** Verify user ID or create user first
  </ResponseField>

  <ResponseField name="Store Not Found" type="error">
    The specified store\_id doesn't exist

    **Status Code:** 404
  </ResponseField>

  <ResponseField name="Duplicate Link" type="error">
    User is already linked to this store

    **Status Code:** 409

    **Solution:** Update existing relationship instead
  </ResponseField>

  <ResponseField name="Invalid Employee ID" type="error">
    The employee\_id format is invalid

    **Status Code:** 400

    **Solution:** Ensure employee\_id is a valid UUID
  </ResponseField>

  <ResponseField name="Permission Denied" type="error">
    User lacks permission to link employees to stores

    **Status Code:** 403
  </ResponseField>
</Accordion>

<Info>
  **Immediate Access:** Once successfully linked, users gain immediate access to store functions based on their assigned access level.
</Info>

<Warning>
  **Security Consideration:** Ensure employee IDs are unique and securely generated to prevent unauthorized access or conflicts.
</Warning>

<Note>
  **Audit Compliance:** All employee linking activities are logged for security audits and compliance requirements.
</Note>