> ## 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 Group

> A segment of customers organized by shared characteristics enabling targeted promotions and personalized experiences.

## Definition

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

In TWICE there is no separate **Group** object. Customer segmentation is implemented through **customer tags**. A "Customer Group" is a named tag that you reuse across publishing, checkout, reporting, and workflows. Tags are flat, free-form, applied manually, and consistent across the platform.

## Where do I use it?

* Charging wholesale customers a different price than retail
* Restricting a Listing so only staff or members can see it
* Hiding or revealing checkout fields based on customer type
* Triggering a Workflow when a customer with a specific tag places an order
* Reporting on revenue, retention, and order frequency per segment
* Bulk-emailing or exporting a segment

## Key Properties

### Tags

A Tag is a string label attached to a Customer. Tags are flat — there is no hierarchy and no parent/child relationship. Plan tag names with care: short, lowercase, hyphenated values (`wholesale`, `vip`, `corporate-acme`, `staff`) read well in filters and stay stable as you add more segments.

| Property                  | Type      | Description                                                                                                                                |
| :------------------------ | :-------- | :----------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                      | String    | Unique identifier of the tag                                                                                                               |
| `value`                   | String    | The tag label shown in admin and used in conditions                                                                                        |
| `scope`                   | Enum      | The resource type the tag applies to — `customers` for customer tags. Other scopes (`inventory`, `catalog`, `orders`) tag other resources. |
| `createdAt` / `updatedAt` | Timestamp | When the tag was created and last changed                                                                                                  |

### Attributes vs Tags

| Layer          | Used for                                                                                                                        |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------ |
| **Tags**       | Manually applied labels on a Customer (e.g. `vip`, `wholesale`, `staff`) — used wherever segmentation drives behavior.          |
| **Attributes** | Structured fields with a typed value on a Customer (e.g. `company`, `vat_id`, `tier`) — visible in admin and usable in filters. |

Membership in a "group" is **manual**: a staff member (or your API integration) sets the tag on the Customer record. There is no rule engine that applies or removes tags automatically.

## Relationships

* A Tag is attached to a [Customer Profile](/docs/concepts/customers/customer-profiles).
* A [Price Table](/docs/concepts/catalog/price-tables) on a Listing can target one or more tags so the matching customer sees a different price.
* A [Listing](/docs/concepts/catalog/listings)'s Publishing settings can restrict visibility to tagged segments.
* A [Workflow](/docs/workflows) can branch on the customer's tags.
* The [Customers table](/docs/customers/overview) can filter, group, and export by tag.

## Lifecycle

### Where Customer Groups are referenced

Customer tags surface anywhere TWICE needs to vary behavior by audience:

<AccordionGroup>
  <Accordion title="Pricing and discounts">
    Price Tables are **not** scoped by customer tags — pricing does not vary by customer group. For customer-specific pricing, target a **discount code** at a tagged segment instead.
  </Accordion>

  <Accordion title="Publishing and channel visibility">
    On the Listing **Publishing** tab, the **Customer tags** card lets you restrict a Listing to specific tagged segments. A Listing flagged `staff` is only visible at checkout for customers carrying that tag.

    This is useful for staff-only rentals, internal demo gear, and member-exclusive listings.
  </Accordion>

  <Accordion title="Checkout flows">
    Combine tags with required [Documents](/docs/concepts/customers/customer-profiles) in your own processes — for example, only confirm orders from a `wholesale`-tagged customer once a signed contract is on file.
  </Accordion>

  <Accordion title="Workflows and automation">
    [Workflows](/docs/workflows) can branch on customer tags — for example, send an extended welcome email when a customer with `wholesale` places their first order, or notify a sales rep when a `corporate-account-acme` booking lands.
  </Accordion>

  <Accordion title="Reporting and exports">
    The Customers table can be filtered and grouped by tag. Order reports can be filtered by the customer's tags at the time the order was placed, so you can analyse revenue, retention, and order frequency per segment.
  </Accordion>
</AccordionGroup>

### Tag taxonomy and management

A few practical rules for keeping tags useful as the catalog grows:

| Practice                        | Why                                                                                                                   |
| :------------------------------ | :-------------------------------------------------------------------------------------------------------------------- |
| Use lowercase, hyphenated names | Reads well in filters and avoids inconsistent matching.                                                               |
| Prefix related tags             | `tier-bronze`, `tier-silver`, `tier-gold` is easier to scan than `bronze`, `silver`, `gold`.                          |
| Keep cardinality low            | Hundreds of tags slow down admin filters. Prefer fewer, broader segments.                                             |
| Reserve technical tags          | Tags like `staff` or `test-account` should only ever be set by admin, not exposed to customers.                       |
| Document your tags              | Keep an internal note describing what each tag gates (visibility, discounts, workflows) so segments stay predictable. |

Tag changes are written to the customer's [Activity Log](/docs/concepts/admin/activity-logs), so you can see when and why a tag was applied or removed.

## FAQs

<AccordionGroup>
  <Accordion title="Is there a Group object I can query directly?">
    No. The "group" is the tag itself. Query customers by `tag` instead, or fetch the Customers table filtered by tag.
  </Accordion>

  <Accordion title="Can a customer be in more than one group?">
    Yes. A Customer can carry multiple tags simultaneously. The pricing engine and publishing rules each decide how to combine them — see Price Tables for the precedence model.
  </Accordion>

  <Accordion title="Can tags be applied automatically?">
    No. There is no tag rule engine — tags are applied and removed manually in admin or via the API. To automate tagging, drive it from your own integration through the `customers` and `tags` endpoints.
  </Accordion>

  <Accordion title="Can I give a single customer a special price?">
    Not through Price Tables — pricing is not scoped by customer tags. Create a **discount code** for the negotiated rate and limit it to that customer or tagged segment instead.
  </Accordion>
</AccordionGroup>

<Note>
  Tags are a flat, free-form list — there is no hierarchy. Plan your tag names with care: short, lowercase, hyphenated values (e.g. `wholesale-tier-1`) read well in filters and stay stable as you add more segments.
</Note>

## Developer Reference

Customer segments are powered by `tags`. Manage tags via the `tags` endpoints and apply them via the `customers` endpoints.

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

## Related

<CardGroup cols={2}>
  <Card title="Customer Profiles" icon="user" href="/docs/concepts/customers/customer-profiles">
    The record a tag is attached to.
  </Card>

  <Card title="Price Tables" icon="table" href="/docs/concepts/catalog/price-tables">
    Reusable listing pricing (not customer-scoped).
  </Card>

  <Card title="Listings" icon="list" href="/docs/concepts/catalog/listings">
    Tag-driven visibility and publishing.
  </Card>

  <Card title="Workflows" icon="diagram-project" href="/docs/workflows">
    Tag-driven automation.
  </Card>
</CardGroup>