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

# Customer Profile

> A comprehensive record of an individual or business customer containing contact information, order history, and preferences.

<Frame caption="Customers > [Customer] > General">
  <img src="https://mintcdn.com/twicecommerce/Ab7tx7ih94KQsi0k/images/customer-general-tab.webp?fit=max&auto=format&n=Ab7tx7ih94KQsi0k&q=85&s=1c68dbe7173b85f8bc139897bcb7ef84" alt="Customer general profile in the admin" width="1920" height="1080" data-path="images/customer-general-tab.webp" />
</Frame>

## Definition

<Snippet file="definitions/customer-profile-definition.mdx" />

A Customer Profile is the single record TWICE uses to identify the person or business on the other side of every transaction. Each profile is referenced by Orders, Reservations, attached documents, the Stock Items currently in the customer's possession, and the tags that drive segmentation across pricing, publishing, and reporting.

## Where do I use it?

* Looking up a customer when creating an Order in admin
* Tracking lifetime value, repeat-rental frequency, and last purchase date
* Attaching signed contracts, ID copies, and insurance certificates to a person
* Granting tag-driven access to staff-only or member-only listings
* Filtering customer reports and exports
* Responding to GDPR access or deletion requests
* Building API integrations that need to look up or create customers

## Key Properties

### Identity and contact

| Property                    | Type      | Description                                                                                                                       |
| :-------------------------- | :-------- | :-------------------------------------------------------------------------------------------------------------------------------- |
| `id`                        | String    | Unique identifier (`cust_*`)                                                                                                      |
| `createdAt`                 | Timestamp | When the profile was created                                                                                                      |
| `firstName`                 | String    | First name (required)                                                                                                             |
| `lastName`                  | String    | Last name                                                                                                                         |
| `email`                     | String    | Primary email — optional in the API, often required in admin. Stored lowercased.                                                  |
| `phone`                     | String    | Contact phone                                                                                                                     |
| `customerType`              | Enum      | `individual` (default) or `business`. Business customers expose additional fields.                                                |
| `companyName`               | String    | Company name (business customers)                                                                                                 |
| `taxId`                     | String    | Tax / VAT ID (business customers)                                                                                                 |
| `dateOfBirth`               | Date      | Date of birth (`YYYY-MM-DD`)                                                                                                      |
| `language`                  | String    | Preferred communication language                                                                                                  |
| `marketingConsent`          | Boolean   | Whether the customer has opted in to marketing                                                                                    |
| `marketingConsentUpdatedAt` | Timestamp | When `marketingConsent` last changed                                                                                              |
| `status`                    | Enum      | `active` (default) or `archived`. Archived customers are kept in the system but excluded from default lists and assignment flows. |

Most of these built-in fields can also be collected from the customer at online checkout. Add them to the Contact step as [customer profile fields](/docs/settings/checkouts/steps) and the submitted values land on the customer record with the order.

### Address and locale

Each customer can have a separate **billing address** and **shipping address**. Used for fulfillment, invoicing, and locale-specific email/document rendering.

### Aggregate data

Customer API responses carry an `aggregateData` object describing the customer collection the record was fetched from:

| Property      | Type              | Description                                               |
| :------------ | :---------------- | :-------------------------------------------------------- |
| `totalCount`  | Integer           | Total number of customer records matching the query       |
| `lastCreated` | Timestamp or null | When the most recent matching customer record was created |
| `lastUpdated` | Timestamp or null | When a matching customer record was last updated          |

Order history is not cached on the profile. The Orders tab and reports read it live from the customer's Orders.

### Attributes

Custom merchant-defined fields beyond the built-in profile fields above. Attributes are grouped into **Attribute groups** configured under **Settings → Attributes**, so you can capture loyalty tier, certification status, dietary requirements, driver's license number, or any other domain-specific data. Each attribute has a format (text, number, boolean, date, select, or multiselect) and stores a typed value on the customer.

<Note>Attributes are separate from profile fields. Built-in fields like `companyName`, `taxId`, and `dateOfBirth` are profile fields — they appear on the General tab. Attributes appear on the Attributes tab and are defined under Settings.</Note>

### Tags

A flat list of labels (`vip`, `wholesale`, `staff`, `corporate-account-acme`) that drives segmentation throughout the platform. Each tag is a `{ value, scope }` pair — customer tags carry `scope: "customers"`. Tags are applied manually in admin or via the API. See [Customer Groups](/docs/concepts/customers/customer-groups) for the full segmentation model.

### Documents

Files attached to the customer — signed contracts, ID copies, insurance certificates, waivers. Each document carries an order index and an optional comment, and is referenced by `fileId` so it can also be linked from a specific Order. Useful for KYC, liability waivers, and audit trails.

## Profile tabs

The Customer detail page is organized into tabs that mirror the data attached to the customer record:

<AccordionGroup>
  <Accordion title="General">
    Built-in profile fields — name, email, phone, date of birth, customer type (individual or business), company name, tax ID, communication language, marketing consent, billing address, and shipping address. Account status (active / archived) is also set here. Tags live in a sidebar card on this tab.
  </Accordion>

  <Accordion title="Attributes">
    Merchant-defined custom fields beyond the built-in profile fields. Grouped by Attribute group, configured under Settings.
  </Accordion>

  <Accordion title="Documents">
    Files attached to the customer. Documents can also be scoped to a specific Order.
  </Accordion>

  <Accordion title="Orders">
    Every Order this customer has placed, regardless of order type. Click an order number to jump to the order detail page.
  </Accordion>

  <Accordion title="Listings">
    [Listings](/docs/concepts/catalog/listings) the customer has interacted with, with the related Order and start date. Useful for spotting repeat-rental patterns per item.
  </Accordion>

  <Accordion title="Stock Items">
    [Stock Items](/docs/concepts/inventory/stock-item-state) currently associated with the customer — typically items that are out on a rental. Each row shows the pickup date and the order number that committed the item.
  </Accordion>

  <Accordion title="Activity Log">
    A scoped audit trail of writes against this customer record. Same columns as the global [Activity Log](/docs/concepts/admin/activity-logs) — Timestamp, Action, Resource type, Actor, Endpoint, Status.
  </Accordion>
</AccordionGroup>

## Relationships

* **Orders** — every Order has a `customerId`. The customer's profile aggregates totals from these.
* **Stock Items** — items currently rented out track the renting customer for the duration of the rental.
* **Documents** — files can be scoped to a customer or to a specific Order.
* **Tags** — drive publishing visibility, targeted discount codes, and segment reporting. See [Customer Groups](/docs/concepts/customers/customer-groups).
* **Attributes** — custom merchant-defined fields that extend the customer record beyond built-in profile fields.
* **Channel** — every Order records the channel it came through (`admin`, `api`, or `online`), useful for analysing acquisition source.

## Lifecycle

### Creation

Customers can be created in several ways:

| Source              | When                                                                                 |
| :------------------ | :----------------------------------------------------------------------------------- |
| **Admin**           | Staff types in details when creating an Order, or directly from the Customers table. |
| **Online checkout** | A customer fills in their details on the storefront and an order is placed.          |
| **API**             | A merchant integration creates the customer via the public API.                      |

If an existing customer matches by email or phone, TWICE links the new order to the existing profile instead of creating a duplicate.

### Updates and merges

* Profile fields can be edited in admin or via API. Edits are written to the Activity Log.
* Order history on the profile reads live from the customer's Orders — there is no per-customer cache to refresh.
* Duplicate profiles can be merged from the Customers table — order history, documents, and tags from both records combine into the surviving profile.

### GDPR and data retention

* **Access**: every field on the customer record is exposed via the API for subject-access requests.
* **Erasure**: customers can be deleted from the admin or via the API. TWICE retains Order-level records (required for accounting and VAT) but strips personally identifiable fields from the deleted customer's profile.
* **Marketing consent**: tracked explicitly as `marketingConsent` and respected by all built-in email flows. Storefront forms surface a consent checkbox tied to this field.
* **Activity Log**: provides an audit trail of who accessed or modified the record.

## FAQs

<AccordionGroup>
  <Accordion title="What's the difference between Attributes and Tags?">
    **Attributes** are custom merchant-defined fields with a key and a typed value — useful for loyalty tiers, certification status, or dietary requirements. **Tags** are flat labels for segmentation. Use Attributes when you need the value itself; use Tags when you need to group customers together.
  </Accordion>

  <Accordion title="Can a Customer have multiple addresses?">
    Yes. The address structure supports separate billing and shipping addresses, and additional addresses can be stored as Attributes for business-specific cases.
  </Accordion>

  <Accordion title="How do I avoid duplicate customers?">
    TWICE matches by email and phone at order creation. If both fields are empty for a new walk-in, you can end up with a duplicate. Use the merge tool on the Customers table to combine records.
  </Accordion>

  <Accordion title="Are deleted customers really gone?">
    Their PII is erased, but the Orders, Payments, and accounting records remain. The link from those Orders to the customer profile is broken.
  </Accordion>

  <Accordion title="Is order history cached on the profile?">
    No. The Orders tab and lifetime metrics read live from the customer's Orders. The `aggregateData` object on API responses describes the customer collection itself (`totalCount`, `lastCreated`, `lastUpdated`), not order history.
  </Accordion>
</AccordionGroup>

## Developer Reference

Customers are exposed as `customers` in the API.

<Card title="API: Customers" icon="code" href="https://server.twicecommerce.com/api/internal">
  Open the endpoint in the API reference.
</Card>

## Related

<CardGroup cols={2}>
  <Card title="Customer Groups" icon="user-group" href="/docs/concepts/customers/customer-groups">
    Segment customers with tags.
  </Card>

  <Card title="Order Lifecycle" icon="rotate" href="/docs/concepts/orders/order-lifecycle">
    The Orders this customer is referenced from.
  </Card>

  <Card title="Price Tables" icon="table" href="/docs/concepts/catalog/price-tables">
    Reusable pricing structures applied to listings (not customer-specific).
  </Card>

  <Card title="Activity Log" icon="clock-rotate-left" href="/docs/concepts/admin/activity-logs">
    Audit trail for customer record edits.
  </Card>

  <Card title="Checkout steps & sections" icon="list-check" href="/docs/settings/checkouts/steps">
    Collect profile fields from the customer at checkout.
  </Card>
</CardGroup>