Bloomcount Public API

REST API for partners and integrations.

Authentication

All endpoints require an Authorization: Bearer bloomcount_... header. Keys are issued from Settings → API in the app and are scoped — a key without products:write cannot create products, etc.

Bulk endpoints

Create / update endpoints accept arrays so a single request can cover up to 500 items. Per-row failures are reported in the errors array rather than failing the whole call.

Idempotency

POST endpoints honour Idempotency-Key. A replay with the same key returns the cached response verbatim; the underlying mutation runs once. Cache TTL is 24 hours, scoped to the API key.

Rate limits & quotas

• Per-key rate limit: 60 requests / minute. Exceeding returns 429 rate_limited.
• Per-tenant monthly cap: configured per plan (default unlimited via the override). Exceeding returns 429 monthly_limit_exceeded.

IDs

IDs are resource-prefixed strings — the prefix tells you what kind of resource the ID refers to. Treat the part after the underscore as opaque (do not parse), but you can rely on the prefix.

Passing the wrong kind of ID (e.g. a var_… where a prod_… is expected) returns 422 wrong_id_type:expected_<table>_got_<table> so the mistake is self-describing. Mismatched / malformed IDs return 422 invalid_id_format or 422 invalid_id_prefix:<prefix>.

Tax Groups

• GET
  List tax groups/api/v1/tax-groups
• POST
  Create or update a tax group/api/v1/tax-groups
• DELETE
  Delete a tax group/api/v1/tax-groups/{id}

Products

• GET
  List products with their variants/api/v1/products
• POST
  Bulk create or update products + variants/api/v1/products
• GET
  Get a single product with its variants/api/v1/products/{id}
• DELETE
  Delete a product/api/v1/products/{id}
• DELETE
  Delete a variant/api/v1/products/{id}/variants/{variantId}

Suppliers

The suppliers that products and per-variant prices can be assigned to. An integration needs a supplier ID before it can write per-supplier prices or per-(variant, supplier) minimum order quantities (MOQ), so it can create its own here rather than waiting for someone to add them in the app. The hidden Default supplier and archived rows aren’t listed.

Suppliers archive rather than delete, because products keep referencing their IDs. Archiving relinks anything left without a supplier to the hidden Default.

• GET
  List suppliers/api/v1/suppliers
• POST
  Create a supplier/api/v1/suppliers
• GET
  Get a single supplier/api/v1/suppliers/{id}
• PATCH
  Update a supplier/api/v1/suppliers/{id}
• POST
  Archive a supplier/api/v1/suppliers/{id}/archive
• POST
  Restore an archived supplier/api/v1/suppliers/{id}/unarchive

Price Lists

• GET
  List price lists/api/v1/price-lists
• POST
  Create or update a price list with optional entries/api/v1/price-lists
• GET
  Get a single price list with its entries/api/v1/price-lists/{id}
• DELETE
  Delete a price list/api/v1/price-lists/{id}

Events

• GET
  List events/api/v1/events
• POST
  Bulk create or update events/api/v1/events
• GET
  Get one event/api/v1/events/{id}
• DELETE
  Delete an event/api/v1/events/{id}
• POST
  Create, update and remove an event's groups/api/v1/events/{id}/groups
• POST
  Add, change and remove an event's lines/api/v1/events/{id}/items

Webhook subscriptions

Manage which URLs receive event deliveries.

• GET
  List webhook subscriptions/api/v1/webhooks
• POST
  Subscribe a URL to event deliveries/api/v1/webhooks
• DELETE
  Delete a webhook subscription/api/v1/webhooks/{id}

Venues

Where events happen. An event references a venue by ID, and the driving distance from your own address is worked out in the background.

• GET
  List venues/api/v1/venues
• POST
  Create a venue/api/v1/venues
• GET
  Get a venue/api/v1/venues/{id}
• DELETE
  Delete a venue/api/v1/venues/{id}
• PATCH
  Update a venue/api/v1/venues/{id}

Staff

The people who work events, with their rates.

• GET
  List staff/api/v1/staff
• POST
  Create a staff member/api/v1/staff
• GET
  Get a staff member/api/v1/staff/{id}
• DELETE
  Delete a staff member/api/v1/staff/{id}
• PATCH
  Update a staff member/api/v1/staff/{id}

Colours

The colour vocabulary. A variant’s colors and an event’s colourScheme are matched by label, not by ID, so listing these is how you learn which labels will match. Renaming one retags everything that used the old label.

• GET
  List colours/api/v1/colors
• POST
  Create a colour/api/v1/colors
• DELETE
  Delete a colour/api/v1/colors/{id}
• PATCH
  Update a colour/api/v1/colors/{id}

Categories

The category vocabulary. A product’s category is matched by label, so listing these is how you learn which labels will match. Renaming one retags every product that carried the old label.

• GET
  List categories/api/v1/categories
• POST
  Create a category/api/v1/categories
• DELETE
  Delete a category/api/v1/categories/{id}
• PATCH
  Update a category/api/v1/categories/{id}