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

Add, change and remove an event's lines

The write side of the groups[].items array that GET /events/{id} returns. A row without itemId creates a line; a row with one updates it; a row with remove: true deletes it.

Consumable lines (the default) need a variantId and a supplierId that sells it. The line’s price is frozen at write time from the event’s price list, so changing the supplier re-freezes it.

Hire lines carry mode: "hire" with hireStart and hireEnd, and need no supplier. They are checked against the variant’s inventory across every overlapping booking: a row that would overbook fails with hire_unavailable:<available>. A line inside a group whose quantityMode is group books quantity × groupQuantity, so the multiplier counts toward that check.

Rows are independent and report their own errors; the event’s totals are recomputed once per call. Send an Idempotency-Key header to make a retry safe.

Pass groupId: null to move a line out of its group; omitting groupId on an update leaves it where it is.

Errors (per row, in errors)

  • variant_id_required / variant_not_found — a create row with no variant, or one that doesn’t exist.
  • item_id_required / item_not_found — an update or remove row naming no line, or one not on this event.
  • invalid_quantity — quantity below 1, or not a whole number.
  • group_not_found — groupId isn’t a group on this event.
  • supplier_id_required — a consumable create row with no supplier.
  • supplier_not_on_variant — that supplier doesn’t sell the variant.
  • supplier_not_allowed_on_hire — hire lines take no supplier.
  • variant_not_hireable — mode: hire on a variant that isn’t hireable.
  • hire_dates_required / hire_end_before_start — a hire line with missing or inverted dates.
  • not_a_hire_line — hire dates sent for a consumable line.
  • hire_unavailable:<available> — the booking would overbook the variant; the suffix is how many units are free across the requested window.

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

POST/api/v1/events/{id}/items
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
itemsEventItemWriteItem[]required
max items 500
Show properties
Array of EventItemWriteItem
itemIdstring
Omit to create a line. Supply it to update or remove that line.
variantIdstring
Required when creating. The product variety the line is for.
supplierIdstring
Required when creating a consumable line, and must be a supplier that sells the variant. Not allowed on hire lines, which have no supplier. Changing it re-freezes the line's price.
quantitynumber
Units for this line. Defaults to 1 on create. Must be above zero.
groupIdstring | null
The group this line belongs to. Pass null to move it out of every group. Omit to leave it where it is.
modestring
consumable is the default and covers stems and materials bought for the event. hire is a studio-owned item rented for a date window and billed per day.
Allowed:consumablehire
hireStartinteger<int64>
Hire lines only. Start of the hire window, epoch milliseconds.
hireEndinteger<int64>
Hire lines only. End of the hire window, epoch milliseconds. Must be on or after hireStart.
removeboolean
Deletes the line. Requires itemId.
Responses
200No row created
resultsobject[]required
Show properties
Array of object
indexintegerrequired
actionstringrequired
Allowed:createdupdatedremoved
itemIdstringrequired
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: - `item_not_found` — the `itemId` is unknown, or belongs to another event or tenant. - `item_id_required` — `remove: true` without an `itemId`. - `variant_id_required` — creating a line without a `variantId`. - `variant_not_found` — the variant is unknown or cross-tenant. - `supplier_id_required` — creating a consumable line without a supplier. - `supplier_not_on_variant` — that supplier doesn't sell the variant. - `supplier_not_allowed_on_hire` — hire lines have no supplier. - `group_not_found` — the `groupId` is not a group on this event. - `invalid_quantity` — quantity is zero or negative. - `variant_not_hireable` — `mode: "hire"` on a variant that isn't rentable. - `hire_dates_required` — a hire line without both `hireStart` and `hireEnd`. - `hire_end_before_start` — the hire window ends before it starts. - `not_a_hire_line` — hire dates sent for a consumable line. - `hire_unavailable:<n>` — the booking would overbook the variant; `<n>` is what is free.
201At least one line created
resultsobject[]required
Show properties
Array of object
indexintegerrequired
actionstringrequired
Allowed:createdupdatedremoved
itemIdstringrequired
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: - `item_not_found` — the `itemId` is unknown, or belongs to another event or tenant. - `item_id_required` — `remove: true` without an `itemId`. - `variant_id_required` — creating a line without a `variantId`. - `variant_not_found` — the variant is unknown or cross-tenant. - `supplier_id_required` — creating a consumable line without a supplier. - `supplier_not_on_variant` — that supplier doesn't sell the variant. - `supplier_not_allowed_on_hire` — hire lines have no supplier. - `group_not_found` — the `groupId` is not a group on this event. - `invalid_quantity` — quantity is zero or negative. - `variant_not_hireable` — `mode: "hire"` on a variant that isn't rentable. - `hire_dates_required` — a hire line without both `hireStart` and `hireEnd`. - `hire_end_before_start` — the hire window ends before it starts. - `not_a_hire_line` — hire dates sent for a consumable line. - `hire_unavailable:<n>` — the booking would overbook the variant; `<n>` is what is free.
400Malformed event ID, or `items` 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/items" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "variantId": "var_h299x7tcqe8rnv4mz12k6yp",
      "supplierId": "sup_77p3v2k6m4t1r5z9c8w0y7b3",
      "quantity": 120,
      "groupId": "evtgrp_3x7c1v9b2n5m8k4j6h0g7f5d"
    },
    {
      "variantId": "var_5t8y2u4i7o1p3a6s9d0f2g4h",
      "mode": "hire",
      "quantity": 8,
      "hireStart": 1810800000000,
      "hireEnd": 1810972800000
    },
    {
      "itemId": "evti_2b1f3x9k4m7p8q6r5t1v0w2y",
      "quantity": 150
    },
    {
      "itemId": "evti_7h4j2k9l5m1n8p3q6r0s4t7v",
      "remove": true
    }
  ]
}'
Response
{
  "results": [
    {
      "index": 0,
      "action": "created",
      "itemId": "string"
    }
  ],
  "errors": [
    {
      "index": 0,
      "error": "string"
    }
  ]
}