Customers

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 group id everywhere in code.
  • Percent groups carry percentBps, 1 to 10000 basis points off the regular price (1500 = 15%, 10000 = free). A fixed group has percentBps: 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_use with details.discounts listing each discount's id, code and name.

The group object

Create a group
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_..." }
}
FieldMeaning
idThe group UUID.
name / kind / percentBps / enabledAs above.
taxExempt / taxExemptReasonOrders 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.
versionInteger, starts at 1. Moves when kind, percentBps, enabled, taxExempt or taxExemptReason changes, not on a rename. Public and stable: caches key on it.
memberCountCustomers in the group.
discountCountDiscounts that name the group.
createdAt / updatedAtISO timestamps.

Routes

Every route is camelCase only and rejects unknown fields with 400 naming the field (for example percent_bps).

RouteScopeNotes
GET /api/v1/customer-groupscustomer_groups:readEvery group of the environment (at most 50), sorted by lower(name) then id. No pagination.
POST /api/v1/customer-groupscustomer_groups:writeBody name, kind, percentBps (required for percent), enabled (default true), taxExempt with taxExemptReason (required together).
GET /api/v1/customer-groups/{id}customer_groups:readOne group.
PATCH /api/v1/customer-groups/{id}customer_groups:writeSwitching 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:writeAnswers removedMemberCount.
POST /api/v1/customer-groups/{id}/memberscustomer_groups:write1 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/removecustomer_groups:writeSame body. Non-members count as unchanged.
POST /api/v1/customer-groups/lookupcustomer_groups:readUp 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.

  • POST and PATCH /api/v1/customers accept customerGroupId (a group id, or null for no group). It needs customer_groups:write as well as customers:write. An unknown or other-environment group is 422 customer_group_not_found before anything is written.
  • Customer responses carry customerGroupId (nullable) only for callers holding customer_groups:read. They then also carry taxExemption: the customer's effective exemption as the merchant sees it ({ v, source, entityUseCode, exemptionNumber, groupId, groupName }, source customer or group), or null when none applies. Buyer proof is not applied here. Resolvers and quote lookups see only the group's taxExempt flag, never the reason.
  • GET /api/v1/customers?customerGroupId=<id> lists the members of a group; customerGroupId=none lists customers in no group. It needs customer_groups:read.
Members
# 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.

Lookup
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.

A members-only code
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.

Silent removal on recalculation and at checkout
Eligibility is judged again whenever the cart is recalculated, including at checkout. If the customer changed, left the group, the group was disabled, or the code expired since it was applied, Throttle drops the code and the totals are recalculated without it. There is no error. A converted cart keeps its snapshot, and orders and subscription renewals keep the discount they were sold with.

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-token header, the token's subject equals the customerId being attached, and the customer has a live credential with a verified email. A claim or merge on the /v1/storefront plane 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).
Attaching a customer with the buyer's token
# 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-token is verified against the same token source as POST /api/v1/storefront/customer-token/introspect: signature, workspace, application and environment, an unrevoked session on the current epoch. CORS allows X-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/sessions must name the customer with customer.customerId to get a basis. A customer named only by email or externalId gets 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 modeEffect for an exempt buyer
AvalaraThe 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).
NativeOnly 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.
OffUnchanged. Nothing is taxed or exempted.

Where the exemption shows up

  • Calculation responses carry a taxExemption snapshot of what was applied. Customer reads carry taxExemption for callers holding customer_groups:read.
  • Every order stores the snapshot in metadata.taxExemption: { v: 1, source, entityUseCode, exemptionNumber, groupId, groupName }, plus netLines and netShipping when the buyer paid net prices. source is customer, group or null (none). The order.created webhook includes it inside data.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-guest instead of the customer id, so an exemption certificate stored in Avalara under that customer cannot apply. The order records this as metadata.taxCustomerCode: "throttle-guest", and its filed document uses the same code. Neither taxExemption nor taxCustomerCode can 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/orders rejects a top-level taxExemption field with 400: 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

StatusCodeWhen
404not_foundNo such group in this environment, or the id is not a UUID.
409customer_group_name_takenAnother group of this environment has the name (ignoring case).
409customer_group_limit_reachedThe environment already has 50 groups.
409customer_group_in_useA discount names the group (details.discounts).
422customer_not_foundA member id is not a customer of this environment (details.customerIds).
422customer_group_not_foundA customerGroupId (customers POST/PATCH) or customerGroupIds entry (discounts POST/PATCH) names no group of this application and environment. Nothing is written.
403insufficient_scopesThe 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.