Catalog

Create a catalog item

Adds an item to a venue's catalog. vat (or its alias vat_rate) omitted takes the standard rate of the venue's country (400 when the venue has none). pricing_mode omitted: per_person when unit_price_per_person > 0, else flat. A plain item needs unit_price.

Package: send is_package: true and components, items of the same venue (plain items, each once). Do not send unit_price, unit_price_per_person or vat: the price is the sum of quantity × unit_price of the components, written to unit_price (or to unit_price_per_person when pricing_mode is per_person), and vat the lowest rate of its items. min_price must not exceed that price. A component without a tax rate takes the standard rate of the venue's country. The response is the package with its derived price and its components. Role permission: quotes.manage (and a venue the member can see).

post/catalog-items

Request

  • Base URL: https://joinways.app/api/v1
  • URL: https://joinways.app/api/v1/catalog-items
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://joinways.app/oauth/authorize, token URL https://joinways.app/api/oauth/token, scopes: mcp.write)

Headers

Idempotency-Keystring

Optional client-generated key (1 to 255 characters, e.g. a UUID v4) that makes the request idempotent for 24 hours: a retry with the same key replays the recorded response (marked Idempotency-Replayed: true) instead of executing the operation again. Same key with another body: 422 idempotency_key_reuse; while the first request runs: 409 idempotency_conflict. See the Idempotency section.

Request body

namestring required
descriptionstring
categorystring
typestring

e.g. Catering, Rental.

unit_labelstring

e.g. per person, per hour.

unit_pricenumber

Excluding tax. Required to create a plain item. Never sent for a package (derived from components).

unit_price_per_personnumber

Never sent for a package.

cost_pricenumber

Internal cost.

min_pricenumber

On a package, at most its price (the sum of its components).

vatnumber

Tax rate in %. Omitted on creation, the standard rate of the venue's country. Never sent for a package (the lowest rate of its items).

vat_ratenumber

Alias of vat (both must agree).

pricing_mode'flat' | 'per_person' | 'tiered'

Omitted on creation, per_person when unit_price_per_person > 0, else flat.

tagsstring[]
is_packageboolean

true with components: the item is a package. false on a package (update): back to a plain item, a price is then required.

venue_idstring uuid required

A venue the member can see.

Example request

{
  "components": [
    {
      "quantity": 1,
      "unit_price": 25
    }
  ]
}

Response

The created item.

idstring uuid
namestring
categorystring nullable
typestring nullable
unit_labelstring nullable
pricing_mode'flat' | 'per_person' | 'tiered'

Which price applies: flat = unit_price per unit, per_person = unit_price_per_person × guests, tiered = the item's price rules.

unit_pricenumber nullable

Price per unit, excluding tax.

unit_price_per_personnumber nullable
cost_pricenumber nullable

Internal cost.

min_pricenumber nullable

Minimum price a quote line may use.

vatnumber nullable

Tax rate in %.

vat_ratenumber nullable

Same value as vat.

taxableboolean nullable
is_packageboolean

The item is a package, made of the items in components. Its price (unit_price, or unit_price_per_person when pricing_mode is per_person) is the sum of quantity × unit_price of its components, and its vat only the lowest of their rates.

created_atstring date-time nullable
updated_atstring date-time nullable
descriptionstring nullable

Create / update only.

tagsstring[] nullable

Create / update only.

location_idstring uuid nullable

Create / update only.

space_idstring uuid nullable

Create / update only.

resolved_unit_pricenumber

Only when pax, date or event_id is passed. Price for that context, price rules applied.

resolved_min_pricenumber nullable

With resolved_unit_price. Floor of the applied rule, else of the catalog.

Example response

{
  "name": "Plated dinner, 3 courses",
  "category": "Catering",
  "type": "Catering",
  "unit_label": "per person",
  "unit_price": 95,
  "vat": 20,
  "vat_rate": 20,
  "components": [
    {
      "name": "Meeting room",
      "quantity": 1,
      "unit_price": 25,
      "vat": 20
    }
  ],
  "applied_price_rule": {
    "label": "High season"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.