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

# User

> The User object represents a customer in your Fungies store.

A User object represents a customer who has made a purchase or registered in your store. Users store identity information including contact details, billing address, and custom identifiers. Each user is automatically created when a customer completes a checkout, or can be created manually via the API.

Users are central to the Fungies platform - they link to [Orders](/core-resources/order), [Payments](/core-resources/payment), [Subscriptions](/core-resources/subscription), and inventory items. You can use the API to create, retrieve, update, and manage user accounts.

## Endpoints

| Method  | Endpoint                       | Description                |
| ------- | ------------------------------ | -------------------------- |
| `GET`   | `/v0/users/list`               | List and filter users      |
| `POST`  | `/v0/users/create`             | Create a new user          |
| `GET`   | `/v0/users/{userId}`           | Retrieve a user            |
| `PATCH` | `/v0/users/{userId}/update`    | Update user details        |
| `PATCH` | `/v0/users/{userId}/archive`   | Archive a user             |
| `PATCH` | `/v0/users/{userId}/unarchive` | Restore an archived user   |
| `GET`   | `/v0/users/{userId}/inventory` | Get user's inventory items |

## The User object

<ResponseField name="object" type="string">
  Object type identifier. Always `"user"` for User objects.
</ResponseField>

<ResponseField name="id" type="string" required>
  Unique identifier (UUID) for this user.
</ResponseField>

<ResponseField name="email" type="string | null">
  The user's email address. Used for transactional emails and account identification.
</ResponseField>

<ResponseField name="username" type="string | null">
  Username of the user, if set. Can be used as an alternative identifier.
</ResponseField>

<ResponseField name="details" type="object | null">
  Billing and contact details for the user.

  <Expandable title="details properties">
    <ResponseField name="type" type="string | null">
      The type of customer account. Possible values: `"individual"`, `"company"`
    </ResponseField>

    <ResponseField name="firstName" type="string | null">
      Customer's first name.
    </ResponseField>

    <ResponseField name="lastName" type="string | null">
      Customer's last name.
    </ResponseField>

    <ResponseField name="phoneNumber" type="string | null">
      Customer's phone number (without country dial code).
    </ResponseField>

    <ResponseField name="dialCode" type="string | null">
      International dial code for the phone number (e.g., `"+1"`, `"+44"`).
    </ResponseField>

    <ResponseField name="address" type="string | null">
      Primary street address line.
    </ResponseField>

    <ResponseField name="addressLine2" type="string | null">
      Secondary address line (apartment, suite, unit, etc.).
    </ResponseField>

    <ResponseField name="city" type="string | null">
      City or locality.
    </ResponseField>

    <ResponseField name="state" type="string | null">
      State, province, or region.
    </ResponseField>

    <ResponseField name="postalCode" type="string | null">
      Postal or ZIP code.
    </ResponseField>

    <ResponseField name="countryCode" type="string | null">
      Two-letter ISO 3166-1 alpha-2 country code (e.g., `"US"`, `"GB"`, `"DE"`).
    </ResponseField>

    <ResponseField name="companyName" type="string | null">
      Company or organization name. Typically set when `type` is `"company"`.
    </ResponseField>

    <ResponseField name="taxId" type="string | null">
      Tax identification type or label.
    </ResponseField>

    <ResponseField name="taxNumber" type="string | null">
      Tax identification number (VAT number, EIN, etc.).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="internalId" type="string | null">
  Your custom identifier for this user. Use this to link Fungies users to your own system's user records.
</ResponseField>

***

## Example response

```json theme={null}
{
  "status": "success",
  "data": {
    "user": {
      "object": "user",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "email": "customer@example.com",
      "username": "johndoe",
      "details": {
        "type": "individual",
        "firstName": "John",
        "lastName": "Doe",
        "dialCode": "+1",
        "phoneNumber": "5551234567",
        "address": "123 Main Street",
        "addressLine2": "Apt 4B",
        "city": "New York",
        "state": "NY",
        "postalCode": "10001",
        "countryCode": "US",
        "companyName": null,
        "taxId": null,
        "taxNumber": null
      },
      "internalId": "usr_abc123"
    }
  }
}
```

***

## Related resources

<CardGroup cols={2}>
  <Card title="Orders" icon="receipt" href="/core-resources/order">
    View orders placed by users
  </Card>

  <Card title="Payments" icon="credit-card" href="/core-resources/payment">
    Payment transactions by users
  </Card>

  <Card title="Subscriptions" icon="rotate" href="/core-resources/subscription">
    User subscription relationships
  </Card>

  <Card title="Events" icon="bell" href="/core-resources/event">
    Webhook events for user activity
  </Card>
</CardGroup>