Catalog

Update a catalog item

Updates the given fields. Setting unit_price_per_person without pricing_mode sets the mode from it. Changing the vat of an item brings the vat of the packages that contain it in line.

Package:

  • components replaces the whole composition (resend every item to keep) and derives the price and the tax rate again, as on creation; pricing_mode may go with it. Sent with is_package: true on a plain item, it turns the item into a package (409 package_component when a package already contains that item).
  • Without components, the price fields (unit_price, unit_price_per_person, pricing_mode) and the tax rate of a package are refused (400 package_price_read_only), like next to components; the other fields can be changed (min_price up to its price).
  • is_package: false turns a package back into a plain item: its composition is removed and a price is required (unit_price or unit_price_per_person, 400 price_required otherwise). Quote lines already made of it keep their articles.

Role permission: quotes.manage (and a venue the member can see).

patch/catalog-items/{id}

Request

  • Base URL: https://joinways.app/api/v1
  • URL: https://joinways.app/api/v1/catalog-items/{id}
  • 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
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.

Example request

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

Response

The updated 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.