Customer Groups
A customer group is a named set of customers. A group is either fixed (the product catalog stores its own prices per variant and currency) or percent (a percentage off the regular price). Groups also decide who may use a promotion code. Manage them in the dashboard under Customers › Groups, or with the API below. In the dashboard dialog, the Pricing field lists Percent off first (the default), then Fixed prices set in the catalog. Without Product Catalog installed in the environment, Pricing is disabled and groups only control who can use group-only discount codes.
Concepts and limits
- Scope. A group belongs to one application and one environment
(production or a sandbox). Another environment's group id answers
404 not_found. - One group per customer. Adding a customer to a group moves them out of any other group. Membership lives in its own table, so the group never appears on a customer unless the call below adds it on purpose.
- At most 50 groups per application and environment. The 51st create answers
409 customer_group_limit_reached(details.limit: 50). - Names are 1 to 100 characters, trimmed, and unique ignoring case
(
409 customer_group_name_taken). Names are labels, not identifiers: use the groupideverywhere in code. - Percent groups carry
percentBps, 1 to 10000 basis points off the regular price (1500 = 15%, 10000 = free). A fixed group haspercentBps: null. - Disabled groups count as no group. Their members get regular prices and are not eligible for codes limited to that group. Memberships stay, so enabling the group restores everything.
- The kind can change. The catalog keeps the fixed prices of a group whatever
its current kind and reads them only while the group is
fixed. - Deleting removes the group and its memberships. A group that a discount
names cannot be deleted:
409 customer_group_in_usewithdetails.discountslisting each discount's id, code and name.
The group object
curl -X POST https://api.usethrottle.dev/api/v1/customer-groups \
-H "x-api-key: $THROTTLE_SECRET_KEY" \
-H "content-type: application/json" \
-d '{ "name": "Wholesale", "kind": "percent", "percentBps": 1500 }'
# 201
{
"data": {
"id": "5e0c1c9e-0a4b-4a52-8d0b-6f1f3a2d7b11",
"name": "Wholesale",
"kind": "percent",
"percentBps": 1500,
"enabled": true,
"taxExempt": false,
"taxExemptReason": null,
"version": 1,
"memberCount": 0,
"discountCount": 0,
"createdAt": "2026-11-11T09:00:00.000Z",
"updatedAt": "2026-11-11T09:00:00.000Z"
},
"meta": { "requestId": "req_..." }
} | Field | Meaning |
|---|---|
id | The group UUID. |
name / kind / percentBps / enabled | As above. |
taxExempt / taxExemptReason | Orders of members are not taxed. The reason is a case-sensitive entity/use code (1 to 25 characters): one of Avalara's standard codes A to R (no O), or, for an app connected to Avalara, a code from its entity/use list. Required when taxExempt is true, null otherwise. PATCH taxExempt false clears the reason. |
version | Integer, starts at 1. Moves when kind, percentBps, enabled, taxExempt or taxExemptReason changes, not on a rename. Public and stable: caches key on it. |
memberCount | Customers in the group. |
discountCount | Discounts that name the group. |
createdAt / updatedAt | ISO timestamps. |
Routes
Every route is camelCase only and rejects unknown fields with 400 naming the field (for example percent_bps).
| Route | Scope | Notes |
|---|---|---|
GET /api/v1/customer-groups | customer_groups:read | Every group of the environment (at most 50), sorted by lower(name) then id. No pagination. |
POST /api/v1/customer-groups | customer_groups:write | Body name, kind, percentBps (required for percent), enabled (default true), taxExempt with taxExemptReason (required together). |
GET /api/v1/customer-groups/{id} | customer_groups:read | One group. |
PATCH /api/v1/customer-groups/{id} | customer_groups:write | Switching to percent needs percentBps; switching to fixed clears it. A PATCH that changes nothing writes nothing and emits no event. |
DELETE /api/v1/customer-groups/{id} | customer_groups:write | Answers removedMemberCount. |
POST /api/v1/customer-groups/{id}/members | customer_groups:write | 1 to 100 customerIds. All or nothing: an id that is not a customer of this environment answers 422 customer_not_found and nothing changes. |
POST /api/v1/customer-groups/{id}/members/remove | customer_groups:write | Same body. Non-members count as unchanged. |
POST /api/v1/customer-groups/lookup | customer_groups:read | Up to 100 customer ids to their groups in one call (below). |
Dashboard users need the matching permission, application:customer-groups:read or application:customer-groups:write (see Permissions). Publishable keys
cannot call these routes, and extensions may request customer_groups:read but not customer_groups:write (see Scopes).
Members: use the customers routes
A customer's group is a field on the customers API for callers who hold the group scopes.
-
POSTandPATCH/api/v1/customersacceptcustomerGroupId(a group id, ornullfor no group). It needscustomer_groups:writeas well ascustomers:write. An unknown or other-environment group is422 customer_group_not_foundbefore anything is written. -
Customer responses carry
customerGroupId(nullable) only for callers holdingcustomer_groups:read. They then also carrytaxExemption: the customer's effective exemption as the merchant sees it ({ v, source, entityUseCode, exemptionNumber, groupId, groupName }, sourcecustomerorgroup), ornullwhen none applies. Buyer proof is not applied here. Resolvers and quote lookups see only the group'staxExemptflag, never the reason. -
GET /api/v1/customers?customerGroupId=<id>lists the members of a group;customerGroupId=nonelists customers in no group. It needscustomer_groups:read.
# Move customers into the group (out of any other group they were in).
curl -X POST https://api.usethrottle.dev/api/v1/customer-groups/$GROUP_ID/members \
-H "x-api-key: $THROTTLE_SECRET_KEY" \
-H "content-type: application/json" \
-d '{ "customerIds": ["<customer uuid>", "<customer uuid>"] }'
# 200
{ "data": { "added": 1, "moved": 1, "unchanged": 0 } }
# List the members of one group, or the customers in no group:
curl "https://api.usethrottle.dev/api/v1/customers?customerGroupId=$GROUP_ID" -H "x-api-key: $THROTTLE_SECRET_KEY"
curl "https://api.usethrottle.dev/api/v1/customers?customerGroupId=none" -H "x-api-key: $THROTTLE_SECRET_KEY" Look up groups for many customers
POST /api/v1/customer-groups/lookup answers the group of up to
100 customers in one call. Customers in no group, unknown customers and other-environment ids
are left out. It has its own rate-limit bucket per key and environment and answers Cache-Control: no-store.
curl -X POST https://api.usethrottle.dev/api/v1/customer-groups/lookup \
-H "x-api-key: $THROTTLE_SECRET_KEY" \
-H "content-type: application/json" \
-d '{ "customerIds": ["<customer uuid>", "<customer uuid>"] }'
# 200: customers in no group and unknown ids are left out
{
"data": {
"memberships": [{ "customerId": "<customer uuid>", "groupId": "5e0c1c9e-..." }],
"groups": [{ "id": "5e0c1c9e-...", "kind": "percent", "percentBps": 1500, "enabled": true, "version": 3, "taxExempt": false, "taxExemptReason": null }]
}
} Import column
A customer import can map a Customer Group column (field customer.customerGroup). Cells name a group, matched ignoring
case in the import's application and environment; none
clears the group. A name that matches no group fails that row with customer_group_not_found. Mapping the column needs customer_groups:write. See Bulk imports.
Events
Four webhook events, readable with customer_groups:read: customer_group.created, customer_group.updated (carries previous values), customer_group.deleted (carries removedMemberCount) and customer_group.members_changed (up to 100 changes of customerId, groupId, previousGroupId, and a source such as api, dashboard or import). The
other three carry the group, including its version. See Webhooks.
Group-limited promotion codes
A discount takes customerGroupIds (0 to 50 ids; needs customer_groups:read). Empty or absent means everyone. On
update, absent leaves the groups as they are and [] clears them.
Every discount response carries customerGroupLimited; only
callers who hold the scope also get customerGroupIds.
curl -X POST https://api.usethrottle.dev/api/v1/discounts \
-H "x-api-key: $THROTTLE_SECRET_KEY" \
-H "content-type: application/json" \
-d '{
"code": "WHOLESALE10",
"name": "Wholesale 10%",
"type": "percentage",
"value": 10,
"customerGroupIds": ["5e0c1c9e-0a4b-4a52-8d0b-6f1f3a2d7b11"]
}' A cart may use a group-limited code only when all of these hold:
- The cart has a customer.
- That customer is a member of one of the named groups, and the group is enabled.
- The customer's identity is proven (next section).
The check runs before every other discount check. An ineligible buyer gets exactly the answer an
unknown code gets (Discount code not found), so the code's
existence is not revealed. The staff routes /discounts/validate and /discounts/preview give the same generic answer.
The legacy catalog /v1/checkout permalink names no customer, so
group-limited codes do not apply there.
Identity proof
Group prices and group-limited codes both need proof of who the buyer is. A customer matched only by an email the buyer typed is never eligible. Throttle records who attached the cart's customer:
- Trusted: the dashboard, or a merchant secret key that is not an extension install key. A checkout session created by such a caller, the order builder and a quote conversion are trusted too. No further proof is needed.
- Storefront session: any other caller (publishable key, extension-install key,
extension session, OAuth token) counts only when the request carries the buyer's own
storefront customer token in the
x-customer-tokenheader, the token's subject equals thecustomerIdbeing attached, and the customer has a live credential with a verified email. A claim or merge on the/v1/storefrontplane needs no header: it records the buyer's attach from their own session. - Nothing: a write without that token records no provenance. The customer is attached, but there are no group prices and no group codes (fail closed).
# A publishable-key or extension-install-key caller attaching a customer to a cart
# must present the buyer's own storefront customer token.
curl -X POST https://api.usethrottle.dev/api/v1/carts \
-H "x-api-key: $THROTTLE_PUBLISHABLE_KEY" \
-H "x-customer-token: $BUYER_CUSTOMER_ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{ "applicationId": "<application uuid>", "currency": "USD", "customerId": "<the token subject>" }' -
x-customer-tokenis verified against the same token source asPOST /api/v1/storefront/customer-token/introspect: signature, workspace, application and environment, an unrevoked session on the current epoch. CORS allowsX-Customer-Token. The header is not declared in the OpenAPI route schemas, so this page and the Cart API guide are where it is documented. -
A non-trusted
POST /api/v1/checkout/sessionsmust name the customer withcustomer.customerIdto get a basis. A customer named only by email orexternalIdgets none. - Every storefront-side attach, claim or merge rewrites the cart's provenance, so an unverified session never inherits a trusted attach a merchant made earlier.
Staff paths (quote lookup, New order in the dashboard) read the customer's membership directly, because only authenticated staff reach them.
Group data for extensions
An extension installation whose pinned version holds an explicit customer_groups:read or customer_groups:write scope receives the buyer's group in
the signed requests Throttle already sends: the line resolver (
customerGroup and identityQualified)
and the quote lookup (customerGroup). The wildcard scope * does not count. An install without the scope never receives
the fields. Catalog-initiated reads (storefront browse, the purchase check) call POST /api/v1/customer-groups/lookup instead.
The product catalog stores only the fixed prices of a group. See Customer prices.
Tax exemption
A group with taxExempt: true makes its members tax exempt. The
group carries one taxExemptReason, an Avalara entity/use code
(case-sensitive; the standard codes A to R except O, or, for an app connected to Avalara, a live
custom code). It is on or off only: there is no partial rate. A disabled group exempts no one.
- Proof is required. An exemption applies only when the caller is trusted (the
dashboard or a merchant secret key) or the request carries the buyer's verified storefront
session in
x-customer-token(see Identity proof). A guest or email-only cart never gets a customer's exemption, and a publishable-key tax quote needs the buyer's token. - The customer's own code wins. When the customer has an entity/use code of their own, it is used and the group's is ignored. An exemption number on the customer alone combines with the group's code.
What each tax mode does
| Tax mode | Effect for an exempt buyer |
|---|---|
| Avalara | The entity/use code is sent to AvaTax and the sale is filed as exempt. On a tax-inclusive destination the buyer pays the net price (two quote steps). |
| Native | Only sales tax and PST components are removed. VAT, GST and HST are kept. On a tax-inclusive destination the buyer pays the net price. |
| Bring your own (resolver) | Flag only. Throttle does not change prices: line-resolver and quote-lookup requests carry customerGroup.taxExempt (to installs that already receive customerGroup), and the customer read carries taxExemption. |
| Off | Unchanged. Nothing is taxed or exempted. |
Where the exemption shows up
-
Calculation responses carry a
taxExemptionsnapshot of what was applied. Customer reads carrytaxExemptionfor callers holdingcustomer_groups:read. -
Every order stores the snapshot in
metadata.taxExemption:{ v: 1, source, entityUseCode, exemptionNumber, groupId, groupName }, plusnetLinesandnetShippingwhen the buyer paid net prices.sourceiscustomer,groupornull(none). Theorder.createdwebhook includes it insidedata.order.metadata. -
When the cart's customer was not proven (a guest typing an email, an unverified
storefront session), Avalara is sent the customer code
throttle-guestinstead of the customer id, so an exemption certificate stored in Avalara under that customer cannot apply. The order records this asmetadata.taxCustomerCode: "throttle-guest", and its filed document uses the same code. NeithertaxExemptionnortaxCustomerCodecan be set or removed through order, cart or import metadata. - Subscription renewals use the exemption in force at renewal time, not at signup. An exempt subscriber stops being charged tax, and on a tax-inclusive destination is charged the net price.
- An accepted quote that was sent to an email attaches the matching customer as proven.
Errors
-
Editing line items of an order whose snapshot holds per-line nets answers
422 tax_exempt_inclusive_edit_unsupported. Cancel the order and create a new one. -
POST /api/v1/ordersrejects a top-leveltaxExemptionfield with400: the exemption is always resolved from the customer.
CLI: throttle customer-groups create|update --tax-exempt --tax-exempt-reason <code>
(update also takes --no-tax-exempt). The MCP group tools take taxExempt and taxExemptReason.
Errors
| Status | Code | When |
|---|---|---|
| 404 | not_found | No such group in this environment, or the id is not a UUID. |
| 409 | customer_group_name_taken | Another group of this environment has the name (ignoring case). |
| 409 | customer_group_limit_reached | The environment already has 50 groups. |
| 409 | customer_group_in_use | A discount names the group (details.discounts). |
| 422 | customer_not_found | A member id is not a customer of this environment (details.customerIds). |
| 422 | customer_group_not_found | A customerGroupId (customers POST/PATCH) or customerGroupIds entry (discounts POST/PATCH) names no group of this application and environment. Nothing is written. |
| 403 | insufficient_scopes | The key lacks a group scope the field needs: customerGroupId on customers POST/PATCH needs customer_groups:write, customerGroupIds on discounts POST/PATCH needs customer_groups:read, and the customers customerGroupId filter needs customer_groups:read. |