Aktionsgruppen (Action Groups)

Read use-api.md first for API basics, sessions and response formats.

Aktionsgruppen group customers by topic, interest or marketing campaign (e.g. "interested in recipes", "newsletter subscriber"). Who may assign a customer to a group is controlled by edittype:

Only edittype = 2 groups are ever exposed through the customer-facing endpoints below.

seeing your own memberships

api/user29 — the authenticated user profile includes actiongroups, the ids of every group the customer currently belongs to.

listing joinable groups

api/system/actiongroups — authenticated; returns every customer-editable (edittype=2) group with a member flag for the current customer. Use this to render a checklist of interests/newsletters in a profile screen.

Groups flagged isad=1 (marketing/advertising groups) are only included if the shop enabled that via configuration (exposeAdActiongroups).

joining / leaving a group

api/client/actiongroup — POST, requires authentication. Parameters agid (target group) and member (1 to join, 0 to leave).

actiongroupids is the resolved membership state after the change — it can differ from a purely optimistic client-side update, since a change may still be pending backend confirmation. Use it to refresh the UI instead of assuming the requested change was applied verbatim.

acting on behalf of another customer (admin only)

An admin session may pass an additional cid parameter to set/remove membership for a different customer. Non-admin sessions that pass a cid other than their own get result = security_error.

pushing a message to a whole group (admin only)

api/admin/pushactiongroup - POST, admin session required. Queues one push notification (title, message, optional imageUrl/linkUrl) for every current member of the group agid as a message series and returns immediately with members (queued pushes) and serieref. Delivery runs in the background; follow sends, failures, delivered and opened counts via stats/mailcampaigns1 with that serieref, and stop the rest via message/series/cancel. Works for every edittype, not only the customer-editable groups. Call it with dryrun=1 first to see members without queueing.

See send-message-series for the general form (SMS, all customers, explicit ids, scheduling) and what to keep in mind.

recommended flow

  1. After logon, read actiongroups from api/user29 (or call api/system/actiongroups for the full list with names) to render the current selection.
  2. On checkbox toggle, POST to api/client/actiongroup with agid/member.
  3. Use the returned actiongroupids as the new source of truth instead of guessing client-side.