# Cardholder Group Management

A cardholder group (CHG) is a collection of one or more cardholders that Percents treats as one reward entity. Cardholders in the same CHG share merchant activation, cashback, and branded balance state, so they can earn rewards and spend branded balance as if they were one.

A CHG commonly maps to authorized users on an account, employees of a business, a household, or another issuer-defined group. Each CHG can have one or more cardholders, and each cardholder can have one or more cards.

Cardholder group management includes:

- The cardholder group record.
- One or more cardholders.
- One or more cards for each cardholder.
- Settings that affect product behavior, localization, or SDK presentation.


The API uses `chg` in path segments and `chg_` typed ids for cardholder group resources.

## Required Flow

1. `POST /api/v2/chg` to create or update one cardholder group.
2. `POST /api/v2/chg/bulk-upsert` when syncing many cardholder groups.
3. `GET /api/v2/chg/{chgId}` to verify the cardholder group Percents stores.
4. Use the cardholder and card ids on card authorization event and settled transaction event ingestion.


## Ownership

All reads and writes are scoped by issuer credentials. A caller must not assume that a syntactically valid `chg_`, `ch_`, or `card_` id is accessible to the current issuer. Percents enforces ownership on API operations.

## Deactivation

Deleting a cardholder group, cardholder, or card is a soft deactivation. Historical transactions, reward events, and audit records remain available for reconciliation.