Customer Groups (beta)
No OAuth-enabled endpoints in this section. Turn off the OAuth filter in the sidebar to see all of its endpoints.
A customer group defines who is charging. Charging policy tariff rules reference customer groups through customerGroupIds: a rule with an empty list applies to every token, and a rule naming one or more groups applies only when the presented token matches at least one filter of at least one of those groups.
A group holds one or more filters, each a type plus a list of values:
| Type | Matched against |
|---|---|
UID | The token's own UID, as read from the card. Use this for a card issued elsewhere, such as a roaming card. |
INTERNAL_TOKEN | The id of an internal token (the generated UUID, not the card's uid). |
ISSUER_NAME | The issuer name reported for a roaming token. |
INFRA_PROVIDER_ID | The country code and party id of the token's mobility provider, concatenated (for example NLTNM). |
ACCOUNT | The id of the account the token belongs to. |
USER | The id of the user the token belongs to. |
TOKEN_BILLING_PLAN | The id of the billing plan attached to the token. |
INTERNAL_TOKEN, ACCOUNT, USER and TOKEN_BILLING_PLAN match on ids the platform issues, so their values must be UUIDs and anything else is rejected on create and update. This is deliberate: authorisation compares the values to ids with an exact string match, so a card uid pasted into an INTERNAL_TOKEN filter would otherwise be stored happily and simply never match.
Which filter applies depends on how the token is authorised, and the two paths do not overlap: an internal token is only ever matched by an INTERNAL_TOKEN filter (its card UID is not compared against UID filters), while a roaming token is matched by all of the other types and never by INTERNAL_TOKEN. ACCOUNT, USER and TOKEN_BILLING_PLAN additionally require the token to be known to Road. UNSPECIFIED is a placeholder and must not be used. Ad-hoc payment (scan-to-pay, tap-to-pay) carries no token identity at all, so a tariff rule that names any customer group is skipped for those sessions.
This API is in preview. It is functional and safe to build against, but breaking changes may still occur; any breaking change is announced in advance.
List Customer Groups
Returns a paginated list of all customer groups for the current provider. Use it to look up the id of a group to reference from a charging policy tariff rule.
User sessionAPI credentialcustomer-groups:readQuery parameters2
200Customer Groups application/json
dataCustomerGroup[]
filtersCustomerGroupFilter[]REQUIREDA token belongs to the group if it matches any one of these filters.
A token belongs to the group if it matches any one of these filters.
What the values are matched against: a token UID, an internal token id, an issuer, a mobility provider, an account, a user, or a billing plan.
ACCOUNTINFRA_PROVIDER_IDINTERNAL_TOKENISSUER_NAMETOKEN_BILLING_PLANUIDUNSPECIFIEDUSERValues to match. For INTERNAL_TOKEN these are internal token ids, not card UIDs.
metaobject
400Invalid Request application/json
errorobject
401Unauthorized application/json
errorobject
403Forbidden: missing a required permission, or no access to this resource application/json
errorobject
404Not Found application/json
errorobject
500Internal server error application/json
errorobject
Create Customer Group
Creates a customer group for the current provider and returns its id, ready to be referenced from a charging policy tariff rule. At least one filter is required; a group with several filters matches a token that satisfies any one of them. Creating the group has no effect on pricing until a tariff rule names it.
User sessionAPI credentialcustomer-groups:writeRequest bodyapplication/json
filtersobject[]REQUIRED
ACCOUNTINFRA_PROVIDER_IDINTERNAL_TOKENISSUER_NAMETOKEN_BILLING_PLANUIDUSER201Created text/plain
400Invalid Request application/json
errorobject
401Unauthorized application/json
errorobject
403Forbidden: missing a required permission, or no access to this resource application/json
errorobject
404Not Found application/json
errorobject
500Internal server error application/json
errorobject
Search Customer Groups
Returns a paginated list of customer groups for the current provider, filtered by ids, free-text query, filter type or creation date range.
User sessionAPI credentialcustomer-groups:readRequest bodyapplication/json
createdAtobject
50min 10min 0200Customer Groups application/json
dataCustomerGroup[]
filtersCustomerGroupFilter[]REQUIREDA token belongs to the group if it matches any one of these filters.
A token belongs to the group if it matches any one of these filters.
What the values are matched against: a token UID, an internal token id, an issuer, a mobility provider, an account, a user, or a billing plan.
ACCOUNTINFRA_PROVIDER_IDINTERNAL_TOKENISSUER_NAMETOKEN_BILLING_PLANUIDUNSPECIFIEDUSERValues to match. For INTERNAL_TOKEN these are internal token ids, not card UIDs.
metaobject
400Invalid Request application/json
errorobject
401Unauthorized application/json
errorobject
403Forbidden: missing a required permission, or no access to this resource application/json
errorobject
404Not Found application/json
errorobject
500Internal server error application/json
errorobject
Update Customer Group
Replaces an existing customer group. The full filters array must be supplied; filters that are not resent are removed. Changes take effect on the next authorisation for every tariff rule that references the group.
User sessionAPI credentialcustomer-groups:writePath parameters1
Request bodyapplication/json
filtersobject[]REQUIRED
ACCOUNTINFRA_PROVIDER_IDINTERNAL_TOKENISSUER_NAMETOKEN_BILLING_PLANUIDUSER204Updated text/plain
400Invalid Request application/json
errorobject
401Unauthorized application/json
errorobject
403Forbidden: missing a required permission, or no access to this resource application/json
errorobject
404Not Found application/json
errorobject
500Internal server error application/json
errorobject
Delete Customer Group
Deletes a customer group. A group that is still referenced by a charging policy tariff rule cannot be deleted; remove it from the rule first, otherwise the request fails.
User sessionAPI credentialcustomer-groups:write