Skip to content
Bloomcount API
Esc
↑↓navigate↵open⌘Jpreview

Create, update and remove an event's groups

One row per group. A row without groupId creates a group; a row with one updates it; a row with remove: true deletes it, moving its lines to moveItemsTo (or leaving them ungrouped when that is omitted).

Rows are independent: a bad reference fails that row only, is reported in errors, and every other row still applies. Send an Idempotency-Key header to make a retry safe — a replay returns the original response without writing again.

Changing quantityMode, groupQuantity or hidden moves the event’s money, so the event’s totals are recomputed once per call.

Errors (per row, in errors)

  • name_required — a create row without a name.
  • group_not_found — groupId isn’t a group on this event.
  • group_id_required — a row asking to remove without naming a group.
  • move_target_not_found — moveItemsTo isn’t a group on this event.
  • move_target_is_removed_group — moveItemsTo names a group this same batch removes.
  • invalid_group_quantity — groupQuantity below 1, or not a whole number.

Whole-request failures: 404 event_not_found, 400 groups_must_be_array, 422 too_many_items above 500 rows.

POST/api/v1/events/{id}/groups
Authorization
AuthorizationBearer token (bloomcount_...) · headerrequired
Path parameters
idstringrequired
Header parameters
Idempotency-Keystring
Replays return the cached response. 24h TTL, scoped per API key.
Request body
requiredapplication/json
groupsEventGroupWriteItem[]required
max items 500
Show properties
Array of EventGroupWriteItem
groupIdstring
Omit to create a group. Supply it to update or remove that group.
namestring
Required when creating. Renames the group when updating.
quantityModestring
open bills each line's own quantity. group multiplies every line in the group by groupQuantity, which is how a table centre repeated across twelve tables is priced.
Allowed:opengroup
groupQuantitynumber
The multiplier used when quantityMode is group. Must be above zero.
hiddenboolean
Hidden groups stay on the event but are excluded from its totals, which is how a proposal offers an option without pricing it.
orderinteger
Sort position in the event. New groups are appended when omitted.
removeboolean
Deletes the group. Requires groupId.
moveItemsTostring
On removal, the group the deleted group's lines move to. They become ungrouped when this is omitted. Must be another group on this event.
Responses
200No row created
resultsobject[]required
Show properties
Array of object
indexintegerrequired
actionstringrequired
Allowed:createdupdatedremoved
groupIdstringrequired
errorsobject[]required
Rows that failed. Every other row still applied.
Show properties
Array of object
indexintegerrequired
Position of the failing row in the array you sent, zero-based.
errorstringrequired
Stable error code. Values: - `group_not_found` — the `groupId` is unknown, or belongs to another event or tenant. - `group_id_required` — `remove: true` without a `groupId`. - `name_required` — creating a group without a name. - `invalid_group_quantity` — `groupQuantity` is zero or negative. - `move_target_not_found` — `moveItemsTo` is not a group on this event. - `move_target_is_removed_group` — `moveItemsTo` points at the group being removed.
201At least one group created
resultsobject[]required
Show properties
Array of object
indexintegerrequired
actionstringrequired
Allowed:createdupdatedremoved
groupIdstringrequired
errorsobject[]required
Rows that failed. Every other row still applied.
Show properties
Array of object
indexintegerrequired
Position of the failing row in the array you sent, zero-based.
errorstringrequired
Stable error code. Values: - `group_not_found` — the `groupId` is unknown, or belongs to another event or tenant. - `group_id_required` — `remove: true` without a `groupId`. - `name_required` — creating a group without a name. - `invalid_group_quantity` — `groupQuantity` is zero or negative. - `move_target_not_found` — `moveItemsTo` is not a group on this event. - `move_target_is_removed_group` — `moveItemsTo` points at the group being removed.
400Malformed event ID, or `groups` is not an array.
errorstringrequired
401Missing or invalid API key, or revoked / expired.
errorstringrequired
403Authenticated, but the key lacks the required scope or the tenant has no API access.
errorstringrequired
404Event not found in the caller's tenant.
errorstringrequired
422Request body or arguments failed validation.
errorstringrequired
429Per-minute rate limit (60/min) or per-month cap exceeded.
errorstringrequired
Try it
Server
Authorization
Parameters
Bodyapplication/json
Request
curl -X POST "https://app.bloomcount.com/api/v1/events/evt_2b1f3x9k4m7p8q6r5t1v0w2y/groups" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "groups": [
    {
      "name": "Bridal bouquets"
    },
    {
      "name": "Table centres",
      "quantityMode": "group",
      "groupQuantity": 8
    },
    {
      "groupId": "evtgrp_9k2m4p7q8r6t5v1w0x3y2z4a",
      "remove": true,
      "moveItemsTo": "evtgrp_3x7c1v9b2n5m8k4j6h0g7f5d"
    }
  ]
}'
Response
{
  "results": [
    {
      "index": 0,
      "action": "created",
      "groupId": "string"
    }
  ],
  "errors": [
    {
      "index": 0,
      "error": "string"
    }
  ]
}