{"openapi":"3.1.0","info":{"title":"Villampiac Vendor API","version":"1.0.0","description":"Public, API-key-authenticated vendor API. Locale-neutral; clients localize from the stable error `code`."},"servers":[{"url":"https://www.flashmob.market/api/v1"}],"security":[{"apiKey":[]}],"paths":{"/analytics":{"get":{"operationId":"getSalesAnalytics","summary":"Ranged sales & traffic analytics","description":"Aggregated sales analytics for the authenticated vendor over an explicit `[from, to]` window. Both bounds are optional ISO-8601 datetimes: when omitted, the endpoint returns the last 30 days. The maximum window is 366 days. Revenue values are decimal strings to preserve precision.","tags":["Analytics"],"x-required-access":"read","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"analytics"},"parameters":[{"in":"query","name":"from","schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$","description":"ISO-8601 start of the period (inclusive).","example":"2026-01-01T00:00:00Z"}},{"in":"query","name":"to","schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$","description":"ISO-8601 end of the period (inclusive).","example":"2026-01-31T23:59:59Z"}}],"responses":{"200":{"description":"Sales analytics for the resolved period.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/customers/by-email":{"get":{"operationId":"getCustomerByEmail","summary":"Customer CRM profile by email","description":"Lifetime value, order cadence, reliability counters, and product/pickup preferences for one customer address. Every figure is computed from the authenticated vendor's own orders — what the customer spent with other vendors is never exposed — except `reliability.trustScore`, which is the marketplace-wide rating tally. Both registered-account orders and guest-checkout orders that captured the address are counted. Returns 404 when the address has no orders with this vendor; an address unknown to the marketplace and one belonging to another vendor's customer are indistinguishable, so this endpoint cannot be used to probe for accounts.","tags":["Customers"],"x-required-access":"read","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"customers"},"parameters":[{"in":"query","name":"email","schema":{"type":"string","maxLength":255,"format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$","description":"Exact customer email address; matching is case-insensitive.","example":"buyer@example.com"},"required":true,"description":"Exact customer email address; matching is case-insensitive."}],"responses":{"200":{"description":"The customer's CRM profile with this vendor.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerCrmResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"This email address has no orders with the authenticated vendor.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/customers/by-phone":{"get":{"operationId":"getCustomerByPhone","summary":"Customer CRM profile by phone","description":"Lifetime value, order cadence, reliability counters, and product/pickup preferences for one customer phone number. Every figure is computed from the authenticated vendor's own orders — what the customer spent with other vendors is never exposed — except `reliability.trustScore`, which is the marketplace-wide rating tally. Both registered-account orders and guest-checkout orders that captured the number are counted. Formatting characters (`+`, spaces, hyphens) are stripped before matching; the response echoes the digits-only number. Returns 404 when the number has no orders with this vendor; a number unknown to the marketplace and one belonging to another vendor's customer are indistinguishable, so this endpoint cannot be used to probe for accounts.","tags":["Customers"],"x-required-access":"read","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"customers"},"parameters":[{"in":"query","name":"phone","schema":{"type":"string","minLength":6,"maxLength":50,"pattern":"^\\+?[\\d\\s-]+$","description":"Exact customer phone number: digits with optional '+', spaces, and hyphens. Formatting is stripped before matching, so '+36 30 123-4567' matches the number stored as '36301234567'; 6–15 digits are required after stripping.","example":"+36 30 123 4567"},"required":true,"description":"Exact customer phone number: digits with optional '+', spaces, and hyphens. Formatting is stripped before matching, so '+36 30 123-4567' matches the number stored as '36301234567'; 6–15 digits are required after stripping."}],"responses":{"200":{"description":"The customer's CRM profile with this vendor.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerCrmByPhoneResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"This phone number has no orders with the authenticated vendor.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/demand-intelligence":{"get":{"operationId":"getDemandIntelligence","summary":"Demand intelligence around a geo anchor","description":"Buyer demand signals plus a restock projection for the authenticated vendor — the decision-support dataset behind \"what should I stock, which event should I join\". The anchor is the request's `lat`/`lng` when both are sent; otherwise the vendor's first private location with coordinates. Without an anchor the demand sections return zeroed and only `supplyForecasts` is populated. The fulfilled rate is a decimal string to preserve precision.","tags":["Demand Intelligence"],"x-required-access":"read","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"demand-intelligence"},"parameters":[{"in":"query","name":"lat","schema":{"description":"Latitude of the demand anchor (decimal degrees). Requires `lng`. When omitted, the vendor's first private location with coordinates is used.","example":47.4979,"type":"number","minimum":-90,"maximum":90},"description":"Latitude of the demand anchor (decimal degrees). Requires `lng`. When omitted, the vendor's first private location with coordinates is used."},{"in":"query","name":"lng","schema":{"description":"Longitude of the demand anchor (decimal degrees). Requires `lat`.","example":19.0402,"type":"number","minimum":-180,"maximum":180},"description":"Longitude of the demand anchor (decimal degrees). Requires `lat`."},{"in":"query","name":"radiusKm","schema":{"default":50,"description":"Search radius in km (1–500).","example":50,"type":"number","minimum":1,"maximum":500},"description":"Search radius in km (1–500)."}],"responses":{"200":{"description":"Demand intelligence for the resolved anchor.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DemandIntelligenceResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/events":{"get":{"operationId":"listEvents","summary":"List events","description":"List the calling vendor's visible events for a tab (upcoming or past), paginated.","tags":["Events"],"x-required-access":"read","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"events"},"parameters":[{"in":"query","name":"tab","schema":{"default":"upcoming","description":"Which events to list.","example":"upcoming","type":"string","enum":["upcoming","past"]},"description":"Which events to list."},{"in":"query","name":"page","schema":{"default":1,"description":"1-based page number (max 1000).","example":1,"type":"integer","minimum":1,"maximum":1000},"description":"1-based page number (max 1000)."},{"in":"query","name":"pageSize","schema":{"default":20,"description":"Items per page (max 100).","example":20,"type":"integer","minimum":1,"maximum":100},"description":"Items per page (max 100)."}],"responses":{"200":{"description":"A page of events.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EventListItem"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"operationId":"createEvent","summary":"Create an event","description":"Create an event at a location managed by the user who created the API key. A location-manager operation — it does not check the calling vendor in. Manager rights are re-checked against the current location manager on every request; a missing, deleted, or non-managed location is a uniform 404. Sending an Idempotency-Key header is strongly recommended.","tags":["Events"],"x-required-access":"write","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"events"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"locationId":{"type":"integer","exclusiveMinimum":0,"maximum":2147483647},"startTime":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},"endTime":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},"hidden":{"default":false,"type":"boolean"}},"required":["locationId","startTime","endTime"]}}}},"responses":{"201":{"description":"The created event.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CreatedEvent"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The API key lacks write permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Location not found (missing, deleted, or not managed by the key's creator).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/events/search":{"get":{"operationId":"searchEvents","summary":"Search joined events","description":"Free-text search across the calling vendor's joined, ongoing/upcoming, non-hidden events, matched by location name or address. Same item shape and page-based pagination as GET /events.","tags":["Events"],"x-required-access":"read","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"events"},"parameters":[{"in":"query","name":"search","schema":{"description":"Match the location name or address of the vendor's joined events.","example":"market","type":"string","minLength":1,"maxLength":200},"description":"Match the location name or address of the vendor's joined events."},{"in":"query","name":"page","schema":{"default":1,"description":"1-based page number (max 1000).","example":1,"type":"integer","minimum":1,"maximum":1000},"description":"1-based page number (max 1000)."},{"in":"query","name":"pageSize","schema":{"default":20,"description":"Items per page (max 100).","example":20,"type":"integer","minimum":1,"maximum":100},"description":"Items per page (max 100)."}],"responses":{"200":{"description":"A page of matching events.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EventListItem"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/events/{id}":{"get":{"operationId":"getEvent","summary":"Get an event","description":"Fetch one event with this vendor's join status and their orders at it.","tags":["Events"],"x-required-access":"read","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"events"},"parameters":[{"in":"path","name":"id","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Positive integer resource id.","example":123},"required":true,"description":"Positive integer resource id."}],"responses":{"200":{"description":"The event detail.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EventDetail"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Event not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"operationId":"updateEvent","summary":"Update an event","description":"Reschedule (startTime/endTime) or hide an event at a location managed by the user who created the API key. A location-manager operation, like POST /events — the calling vendor's join status is irrelevant. At least one field is required and the event cannot be moved to another location. Omitted times keep their stored value and the merged range is validated, so sending endTime alone can still fail with 422. Hiding an event is the non-destructive alternative to DELETE: it disappears from vendor and public surfaces while its orders stay intact.","tags":["Events"],"x-required-access":"write","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"events"},"parameters":[{"in":"path","name":"id","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Positive integer resource id.","example":123},"required":true,"description":"Positive integer resource id."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"startTime":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},"endTime":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},"hidden":{"type":"boolean"}}}}}},"responses":{"200":{"description":"The updated event.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CreatedEvent"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The API key lacks write permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Event not found (missing, or its location is not managed by the key's creator).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"A business rule blocks the update.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"operationId":"deleteEvent","summary":"Delete an event","description":"Delete an event at a location managed by the user who created the API key, together with the vendor check-ins on it. A location-manager operation, like POST /events. Refused with 409 while the event has active orders (confirmed, vendor_confirmed, paid) or while any other record still references it (a cart, a cancelled order, an RSVP); the error names the blocking rule in details.code. Use PATCH with hidden: true when the event must survive but stop being visible.","tags":["Events"],"x-required-access":"write","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"events"},"parameters":[{"in":"path","name":"id","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Positive integer resource id.","example":123},"required":true,"description":"Positive integer resource id."}],"responses":{"200":{"description":"The event was deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeletedEvent"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The API key lacks write permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Event not found (missing, or its location is not managed by the key's creator).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Active orders or other referencing records block the delete.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/events/{id}/check-in":{"post":{"operationId":"checkInToEvent","summary":"Check in to an event","description":"Subscribe the calling vendor to an event. Idempotent — a repeat check-in succeeds.","tags":["Events"],"x-required-access":"write","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"events"},"parameters":[{"in":"path","name":"id","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Positive integer resource id.","example":123},"required":true,"description":"Positive integer resource id."}],"responses":{"200":{"description":"Checked in.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EventMembershipResult"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The API key lacks write permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Event not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"The event has ended or the location is not joinable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/events/{id}/check-out":{"post":{"operationId":"checkOutOfEvent","summary":"Check out of an event","description":"Unsubscribe the calling vendor from an event, even with active orders. Stops new orders while preserving existing orders for fulfilment. Idempotent — leaving an absent membership succeeds.","tags":["Events"],"x-required-access":"write","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"events"},"parameters":[{"in":"path","name":"id","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Positive integer resource id.","example":123},"required":true,"description":"Positive integer resource id."}],"responses":{"200":{"description":"Checked out.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EventMembershipResult"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The API key lacks write permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/managed-locations":{"get":{"operationId":"listManagedLocations","summary":"List managed locations","description":"List the non-deleted locations currently managed by the user who created the API key, ordered by name then id. A key whose creator manages no locations gets an empty page, not an error.","tags":["Managed locations"],"x-required-access":"read","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"managed-locations"},"parameters":[{"in":"query","name":"page","schema":{"default":1,"description":"1-based page number (max 1000).","example":1,"type":"integer","minimum":1,"maximum":1000},"description":"1-based page number (max 1000)."},{"in":"query","name":"pageSize","schema":{"default":20,"description":"Items per page (max 100).","example":20,"type":"integer","minimum":1,"maximum":100},"description":"Items per page (max 100)."}],"responses":{"200":{"description":"A page of managed locations.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagedLocationListResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/managed-locations/{id}":{"get":{"operationId":"getManagedLocation","summary":"Get a managed location","description":"Fetch the full detail, including the image gallery, of a location managed by the user who created the API key. Manager rights are re-checked on every request; a missing, deleted, or non-managed location is a uniform 404.","tags":["Managed locations"],"x-required-access":"read","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"managed-locations"},"parameters":[{"in":"path","name":"id","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Positive integer resource id.","example":123},"required":true,"description":"Positive integer resource id."}],"responses":{"200":{"description":"The location detail.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ManagedLocationDetail"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Location not found (missing, deleted, or not managed by the key's creator).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"operationId":"updateManagedLocation","summary":"Update a managed location","description":"Update fields of a location managed by the user who created the API key. A missing, deleted, or non-managed location is a uniform 404.","tags":["Managed locations"],"x-required-access":"write","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"managed-locations"},"parameters":[{"in":"path","name":"id","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Positive integer resource id.","example":123},"required":true,"description":"Positive integer resource id."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"address":{"type":"string","minLength":1,"maxLength":500},"city":{"anyOf":[{"type":"string","minLength":1,"maxLength":255},{"type":"null"}]},"filterTags":{"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":100}},"url":{"anyOf":[{"type":"string","maxLength":500,"format":"uri"},{"type":"null"}]},"latitude":{"anyOf":[{"type":"number","minimum":-90,"maximum":90},{"type":"null"}]},"longitude":{"anyOf":[{"type":"number","minimum":-180,"maximum":180},{"type":"null"}]},"accessMode":{"type":"string","enum":["open","restricted"]},"vendorDescription":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}]}},"additionalProperties":false}}}},"responses":{"200":{"description":"The updated location detail.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ManagedLocationDetail"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The API key lacks write permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Location not found (missing, deleted, or not managed by the key's creator).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"A vendor-owned location's access mode cannot be changed by its organizer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/managed-locations/{id}/images":{"get":{"operationId":"listManagedLocationImages","summary":"List location images","description":"List the image gallery of a location managed by the user who created the API key, in display order. A missing, deleted, or non-managed location is a uniform 404.","tags":["Managed locations"],"x-required-access":"read","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"managed-locations"},"parameters":[{"in":"path","name":"id","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Positive integer resource id.","example":123},"required":true,"description":"Positive integer resource id."}],"responses":{"200":{"description":"The location's images.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ManagedLocationImage"}}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Location not found (missing, deleted, or not managed by the key's creator).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"operationId":"confirmManagedLocationImage","summary":"Confirm an image upload","description":"Confirm a previously presigned gallery upload, attaching the stored image to a location managed by the user who created the API key. A missing, deleted, or non-managed location is a uniform 404.","tags":["Managed locations"],"x-required-access":"write","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"managed-locations"},"parameters":[{"in":"path","name":"id","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Positive integer resource id.","example":123},"required":true,"description":"Positive integer resource id."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"imageUrl":{"type":"string","maxLength":500,"format":"uri"},"key":{"type":"string","minLength":1,"maxLength":500},"altText":{"type":"string","maxLength":255}},"required":["imageUrl","key"],"additionalProperties":false}}}},"responses":{"201":{"description":"The confirmed image.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ManagedLocationImage"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The API key lacks write permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Location not found (missing, deleted, or not managed by the key's creator).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"The location already has the maximum number of gallery images.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/managed-locations/{id}/images/presign":{"post":{"operationId":"presignManagedLocationImageUpload","summary":"Presign an image upload","description":"Create a presigned R2 upload URL for a new gallery image of a location managed by the user who created the API key. PUT the file bytes directly to `uploadUrl` within 5 minutes, then confirm the upload via POST /managed-locations/{id}/images. A missing, deleted, or non-managed location is a uniform 404.","tags":["Managed locations"],"x-required-access":"write","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"managed-locations"},"parameters":[{"in":"path","name":"id","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Positive integer resource id.","example":123},"required":true,"description":"Positive integer resource id."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"contentType":{"type":"string","enum":["image/jpeg","image/png","image/webp","image/gif"]},"contentLength":{"type":"integer","exclusiveMinimum":0,"maximum":5242880}},"required":["contentType","contentLength"],"additionalProperties":false}}}},"responses":{"200":{"description":"Presigned upload data.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ManagedLocationImagePresign"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The API key lacks write permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Location not found (missing, deleted, or not managed by the key's creator).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/managed-locations/{id}/images/{imageId}":{"patch":{"operationId":"updateManagedLocationImage","summary":"Update a location image","description":"Update gallery metadata (alt text, primary flag) of one image of a location managed by the user who created the API key. A missing, deleted, or non-managed location or image is a uniform 404.","tags":["Managed locations"],"x-required-access":"write","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"managed-locations"},"parameters":[{"in":"path","name":"id","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Positive integer resource id.","example":123},"required":true,"description":"Positive integer resource id."},{"in":"path","name":"imageId","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Positive integer resource id.","example":123},"required":true,"description":"Positive integer resource id."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"altText":{"type":"string","maxLength":255},"isPrimary":{"type":"boolean","const":true}},"additionalProperties":false}}}},"responses":{"200":{"description":"The updated image.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ManagedLocationImage"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The API key lacks write permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Location or image not found (missing, deleted, or not managed by the key's creator).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"operationId":"deleteManagedLocationImage","summary":"Delete a location image","description":"Remove one image from the gallery of a location managed by the user who created the API key. The underlying R2 object is deleted on a best-effort basis. A missing, deleted, or non-managed location or image is a uniform 404.","tags":["Managed locations"],"x-required-access":"write","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"managed-locations"},"parameters":[{"in":"path","name":"id","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Positive integer resource id.","example":123},"required":true,"description":"Positive integer resource id."},{"in":"path","name":"imageId","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Positive integer resource id.","example":123},"required":true,"description":"Positive integer resource id."}],"responses":{"200":{"description":"Image deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeletedLocationImageResult"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The API key lacks write permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Location or image not found (missing, deleted, or not managed by the key's creator).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/managed-locations/{id}/images/order":{"put":{"operationId":"reorderManagedLocationImages","summary":"Reorder location images","description":"Set the display order of the whole gallery of a location managed by the user who created the API key. A missing, deleted, or non-managed location is a uniform 404.","tags":["Managed locations"],"x-required-access":"write","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"managed-locations"},"parameters":[{"in":"path","name":"id","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Positive integer resource id.","example":123},"required":true,"description":"Positive integer resource id."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"orderedIds":{"minItems":1,"type":"array","items":{"type":"integer","exclusiveMinimum":0,"maximum":2147483647}}},"required":["orderedIds"],"additionalProperties":false}}}},"responses":{"200":{"description":"The reordered image ids.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ReorderedLocationImagesResult"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The API key lacks write permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Location not found (missing, deleted, or not managed by the key's creator).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/orders":{"get":{"operationId":"listOrders","summary":"List the authenticated vendor's orders.","tags":["Orders"],"x-required-access":"read","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"orders"},"parameters":[{"in":"query","name":"page","schema":{"default":1,"description":"1-based page number (max 1000).","example":1,"type":"integer","minimum":1,"maximum":1000},"description":"1-based page number (max 1000)."},{"in":"query","name":"pageSize","schema":{"default":20,"description":"Items per page (max 100).","example":20,"type":"integer","minimum":1,"maximum":100},"description":"Items per page (max 100)."},{"in":"query","name":"state","schema":{"description":"Filter by order state.","type":"string","enum":["confirmed","vendor_confirmed","paid","picked_up","cancelled","rejected","no_show"]},"description":"Filter by order state."},{"in":"query","name":"paymentState","schema":{"description":"Filter by payment state.","type":"string","enum":["pending","paid","refunded"]},"description":"Filter by payment state."},{"in":"query","name":"paymentMethod","schema":{"description":"Filter by recorded payment method (e.g. `card`).","type":"string","enum":["card","cash","wire_transfer","gift","crypto"]},"description":"Filter by recorded payment method (e.g. `card`)."},{"in":"query","name":"eventId","schema":{"description":"Only return orders placed for this pickup event.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"example":123},"description":"Only return orders placed for this pickup event."},{"in":"query","name":"search","schema":{"description":"Match order number or customer name/email/phone.","type":"string","maxLength":200},"description":"Match order number or customer name/email/phone."},{"in":"query","name":"receivable","schema":{"description":"Only orders with an open payment request (`open`), or one past its due date (`overdue`).","type":"string","enum":["open","overdue"]},"description":"Only orders with an open payment request (`open`), or one past its due date (`overdue`)."},{"in":"query","name":"completedFrom","schema":{"description":"Inclusive start of an order-time window. Order time is `completedAt`, or `createdAt` when the order has no `completedAt` (e.g. paid but not picked up). ISO-8601 with an offset; URL-encode `+` as `%2B`.","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},"description":"Inclusive start of an order-time window. Order time is `completedAt`, or `createdAt` when the order has no `completedAt` (e.g. paid but not picked up). ISO-8601 with an offset; URL-encode `+` as `%2B`."},{"in":"query","name":"completedTo","schema":{"description":"Exclusive end of the order-time window (`completedAt`, else `createdAt`). ISO-8601 with an offset; URL-encode `+` as `%2B`.","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},"description":"Exclusive end of the order-time window (`completedAt`, else `createdAt`). ISO-8601 with an offset; URL-encode `+` as `%2B`."}],"responses":{"200":{"description":"A page of orders.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"operationId":"createOrder","summary":"Create a pickup-event preorder for an existing customer.","description":"Requires a read_write key and Idempotency-Key. Resolves customerEmail only inside the authenticated vendor scope, creates a vendor_confirmed preorder, and computes prices server-side. Does not notify the customer; the integration is responsible for buyer communication.","tags":["Orders"],"x-required-access":"write","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"orders"},"parameters":[{"in":"header","name":"Idempotency-Key","schema":{"type":"string","minLength":1,"maxLength":255,"description":"Unique key for this logical write operation."},"required":true,"description":"Unique key for this logical write operation."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"customerEmail":{"type":"string","maxLength":255,"format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"eventId":{"type":"integer","exclusiveMinimum":0,"maximum":2147483647},"paymentMethod":{"type":"string","enum":["card","cash","wire_transfer","gift","crypto"]},"note":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"items":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"productId":{"type":"integer","exclusiveMinimum":0,"maximum":2147483647},"quantity":{"type":"integer","minimum":1,"maximum":999},"weightGrams":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":999999},{"type":"null"}]},"selectedOptions":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["productId","quantity"]}}},"required":["customerEmail","eventId","paymentMethod","items"]}}}},"responses":{"201":{"description":"The created order.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"number":{"type":"string"},"state":{"type":"string","const":"vendor_confirmed"},"total":{"type":"string"},"noSupplyProductIds":{"description":"Product ids stored without a supply pool covering the complete pickup window — nothing was reserved for them. Informational; vendor-performed orders may oversell. Absent when every item was reserved.","type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}}},"required":["id","number","state","total"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The API key lacks write permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Customer or referenced vendor resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/orders/{id}":{"get":{"operationId":"getOrder","summary":"Fetch one of the authenticated vendor's orders.","tags":["Orders"],"x-required-access":"read","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"orders"},"parameters":[{"in":"path","name":"id","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Positive integer resource id.","example":123},"required":true,"description":"Positive integer resource id."}],"responses":{"200":{"description":"The order.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OrderDetail"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Order not found for this vendor.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/orders/by-email":{"get":{"operationId":"listOrdersByEmail","summary":"Find this vendor's orders by exact customer email.","description":"Case-insensitive exact match against registered-customer and historical guest order email, scoped to the authenticated vendor.","tags":["Orders"],"x-required-access":"read","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"orders"},"parameters":[{"in":"query","name":"page","schema":{"default":1,"type":"integer","minimum":1,"maximum":1000}},{"in":"query","name":"pageSize","schema":{"default":20,"type":"integer","minimum":1,"maximum":100}},{"in":"query","name":"email","schema":{"type":"string","maxLength":255,"format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"required":true}],"responses":{"200":{"description":"A page of matching orders.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/orders/by-event/{eventId}":{"get":{"operationId":"listOrdersByEvent","summary":"List the authenticated vendor's orders at one event.","description":"Paginated like the other list routes, with one compatibility carve-out: `pageSize` defaults to the maximum (100) instead of 20, so integrations predating pagination see an unchanged response below one page.","tags":["Orders"],"x-required-access":"read","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"orders"},"parameters":[{"in":"path","name":"eventId","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Positive integer resource id.","example":123},"required":true,"description":"Positive integer resource id."},{"in":"query","name":"page","schema":{"default":1,"description":"1-based page number (max 1000).","example":1,"type":"integer","minimum":1,"maximum":1000},"description":"1-based page number (max 1000)."},{"in":"query","name":"pageSize","schema":{"default":100,"description":"Orders per page (max 100, defaults to the max for backward compatibility).","example":100,"type":"integer","minimum":1,"maximum":100},"description":"Orders per page (max 100, defaults to the max for backward compatibility)."}],"responses":{"200":{"description":"The event summary and a page of its orders.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"event":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"startTime":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},"endTime":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},"locationName":{"anyOf":[{"type":"string"},{"type":"null"}]},"locationAddress":{"anyOf":[{"type":"string"},{"type":"null"}]},"isJoined":{"type":"boolean"}},"required":["id","startTime","endTime","locationName","locationAddress","isJoined"],"additionalProperties":false},"orders":{"type":"array","items":{"$ref":"#/components/schemas/EventOrder"}}},"required":["event","orders"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Event not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/orders/{id}/items":{"put":{"operationId":"replaceOrderItems","summary":"Replace an editable order's complete item list.","description":"Requires a read_write key and Idempotency-Key. Existing rows keep their id, new rows omit it, and omitted rows are deleted. Prices are computed or preserved by the shared vendor edit workflow.","tags":["Orders"],"x-required-access":"write","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"orders"},"parameters":[{"in":"path","name":"id","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Positive integer resource id.","example":123},"required":true,"description":"Positive integer resource id."},{"in":"header","name":"Idempotency-Key","schema":{"type":"string","minLength":1,"maxLength":255,"description":"Unique key for this logical write operation."},"required":true,"description":"Unique key for this logical write operation."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"productId":{"type":"integer","exclusiveMinimum":0,"maximum":2147483647},"quantity":{"type":"integer","minimum":1,"maximum":999},"weightGrams":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":999999},{"type":"null"}]},"selectedOptions":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},{"type":"null"}]},"id":{"type":"integer","exclusiveMinimum":0,"maximum":2147483647}},"required":["productId","quantity"]}}},"required":["items"]}}}},"responses":{"200":{"description":"The order's recalculated total.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"total":{"type":"string"},"noSupplyProductIds":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}}},"required":["id","total"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The API key lacks write permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Order not found for this vendor.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/orders/{id}/state":{"post":{"operationId":"updateOrderState","summary":"Transition one of the authenticated vendor's orders to a new state.","description":"Requires a read_write key. Allowed transitions, inventory release, receipt generation, and buyer notification are enforced by the shared order workflow.","tags":["Orders"],"x-required-access":"write","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"orders"},"parameters":[{"in":"path","name":"id","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Positive integer resource id.","example":123},"required":true,"description":"Positive integer resource id."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"state":{"type":"string","enum":["vendor_confirmed","paid","picked_up","cancelled","rejected","no_show"],"description":"Target order state."},"paymentMethod":{"type":"string","enum":["card","cash","wire_transfer","gift","crypto"]},"cancellationReason":{"type":"string","maxLength":2000}},"required":["state"]}}}},"responses":{"200":{"description":"The order's new state.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"state":{"type":"string","enum":["vendor_confirmed","paid","picked_up","cancelled","rejected","no_show"]}},"required":["id","state"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The API key lacks write permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Order not found for this vendor.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/orders/{id}/event":{"post":{"operationId":"moveOrderToEvent","summary":"Move one of the authenticated vendor's orders to another pickup event.","description":"Requires a read_write key and Idempotency-Key. Vendor-performed move of a confirmed or vendor_confirmed order to another event this vendor attends. Exempt from order-deadline and preparation-time gating; supply is re-attached best-effort and may intentionally oversell. When the customer already has an open order on the target event, the orders are merged and the source order is cancelled.","tags":["Orders"],"x-required-access":"write","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"orders"},"parameters":[{"in":"path","name":"id","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Positive integer resource id.","example":123},"required":true,"description":"Positive integer resource id."},{"in":"header","name":"Idempotency-Key","schema":{"type":"string","minLength":1,"maxLength":255,"description":"Unique key for this logical write operation."},"required":true,"description":"Unique key for this logical write operation."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"eventId":{"type":"integer","exclusiveMinimum":0,"maximum":2147483647}},"required":["eventId"]}}}},"responses":{"200":{"description":"The surviving order after the move.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Id of the surviving order (the merge target when merged is true)."},"number":{"type":"string"},"eventId":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The order's new pickup event id."},"merged":{"type":"boolean","description":"True when the order was merged into the customer's existing open order on the target event; the source order is then cancelled."},"total":{"type":"string","description":"Decimal string total of the surviving order."},"noSupplyProductIds":{"description":"Product ids re-attached without a matching supply window — informational; vendor-performed moves may oversell.","type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}}},"required":["id","number","eventId","merged","total"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The API key lacks write permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Order or target event not found for this vendor.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/orders/guest":{"post":{"operationId":"createGuestOrder","summary":"Create a pickup pre-order for a customer identified by email only.","description":"Requires a read_write key and Idempotency-Key. Unlike POST /orders, the customer does not have to be known to this vendor: an unknown email gets a new inactive account and an activation invitation email; a known email is linked to this vendor and gets an order confirmation email. The order is created vendor_confirmed with pending payment, prices are computed server-side, and vendor-performed inventory rules apply (may oversell, exempt from preparation-time gating).","tags":["Orders"],"x-required-access":"write","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"orders"},"parameters":[{"in":"header","name":"Idempotency-Key","schema":{"type":"string","minLength":1,"maxLength":255,"description":"Unique key for this logical write operation."},"required":true,"description":"Unique key for this logical write operation."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"customerEmail":{"type":"string","maxLength":255,"format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"firstName":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"lastName":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"phone":{"anyOf":[{"type":"string","minLength":3,"maxLength":50},{"type":"null"}]},"eventId":{"type":"integer","exclusiveMinimum":0,"maximum":2147483647},"paymentMethod":{"type":"string","enum":["card","cash","wire_transfer","gift","crypto"]},"note":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"locale":{"type":"string","enum":["en","hu","fi","sv","ro","de"]},"items":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"productId":{"type":"integer","exclusiveMinimum":0,"maximum":2147483647},"quantity":{"type":"integer","minimum":1,"maximum":999},"weightGrams":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":999999},{"type":"null"}]},"selectedOptions":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["productId","quantity"]}}},"required":["customerEmail","eventId","paymentMethod","items"]}}}},"responses":{"201":{"description":"The created guest pre-order.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"number":{"type":"string"},"state":{"type":"string","const":"vendor_confirmed"},"total":{"type":"string"},"isNewCustomer":{"type":"boolean","description":"True when a new inactive account was created and an activation invitation email was sent to the customer."},"noSupplyProductIds":{"description":"Product ids stored without a supply pool covering the complete pickup window — nothing was reserved for them. Informational; vendor-performed orders may oversell. Absent when every item was reserved.","type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}}},"required":["id","number","state","total","isNewCustomer"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The API key lacks write permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Referenced vendor resource (event or product) not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/orders/{id}/vendor-note":{"put":{"operationId":"updateOrderVendorNote","summary":"Replace the internal vendor note on one of the authenticated vendor's orders.","description":"Requires a read_write key. Full replacement of the order's internal vendor note (not the buyer-facing note); send null to clear it. The note is visible in the vendor dashboard and in every order read of this API.","tags":["Orders"],"x-required-access":"write","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"orders"},"parameters":[{"in":"path","name":"id","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Positive integer resource id.","example":123},"required":true,"description":"Positive integer resource id."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"vendorNote":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]}},"required":["vendorNote"]}}}},"responses":{"200":{"description":"The order's new vendor note.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"vendorNote":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","vendorNote"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The API key lacks write permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Order not found for this vendor.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/orders/{id}/delivery":{"patch":{"operationId":"updateOrderDelivery","summary":"Report courier progress on one of the vendor's home-delivery orders.","description":"Requires a read_write key. Advances the delivery sub-status (pending, out_for_delivery, delivered) and/or sets the buyer-facing tracking URL on a home-delivery order. Status is monotonic: same-status retries are allowed, but backward transitions answer 409. The sub-status does not move the order state: moving an order to picked_up marks its delivery delivered, but reporting delivered here leaves the order state alone. Orders without a delivery address — every pickup order — answer 404.","tags":["Orders"],"x-required-access":"write","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"orders"},"parameters":[{"in":"path","name":"id","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Positive integer resource id.","example":123},"required":true,"description":"Positive integer resource id."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"deliveryStatus":{"type":"string","enum":["pending","out_for_delivery","delivered"]},"trackingUrl":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]}}}}}},"responses":{"200":{"description":"The order's delivery progress.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"deliveryStatus":{"type":"string","enum":["pending","out_for_delivery","delivered"]},"trackingUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","deliveryStatus","trackingUrl"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The API key lacks write permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Order not found for this vendor, or it is not a delivery order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"The requested delivery status would move backwards.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/orders/{id}/payment-request":{"get":{"operationId":"getOrderPaymentRequest","summary":"Read an order's payment request and whether a new one can be issued.","description":"Returns `paymentRequest`, the order's newest open payment request, else its newest in any status (null when none was issued); `paymentRequests`, every non-superseded request (one per sales profile can be open); and the issue eligibility: blocking reasons, prefilled buyer name/email and due date, and the `baseline` to send back as `expectedBaseline` when issuing.","tags":["Orders"],"x-required-access":"read","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"orders"},"parameters":[{"in":"path","name":"id","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Positive integer resource id.","example":123},"required":true,"description":"Positive integer resource id."}],"responses":{"200":{"description":"The payment request and issue eligibility.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"paymentRequest":{"anyOf":[{"$ref":"#/components/schemas/PaymentRequest"},{"type":"null"}],"description":"The order's newest open request, else its newest in any status; null when none was issued."},"paymentRequests":{"type":"array","items":{"$ref":"#/components/schemas/PaymentRequest"},"description":"Every non-superseded payment request of the order, newest first; one per sales profile can be open."},"eligibility":{"$ref":"#/components/schemas/PaymentRequestEligibility"}},"required":["paymentRequest","paymentRequests","eligibility"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Order not found for this vendor.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"operationId":"issueOrderPaymentRequest","summary":"Issue a payment request for an order and email it to the buyer.","description":"Requires a read_write key and Idempotency-Key. Issues a bank-transfer payment request (PDF emailed to the buyer) for a confirmed or vendor_confirmed order, or a picked_up order whose payment is still pending; issuing a confirmed order also moves it to vendor_confirmed. While a request is open, a repeat returns it with created=false (200) and this call sends no new email; to replace it send reissue=true with supersedesId set to the open request's id. A re-issue naming a stale supersedesId also returns the current open request with created=false. Every refusal carries a code in `details.reason`: 404 not_found for order_not_found and request_not_found; 409 conflict for baseline_changed (with the current `details.baseline`), request_not_open and request_stale; 422 validation_error for the order preconditions; 429 rate_limited for send_limit_reached.","tags":["Orders"],"x-required-access":"write","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"orders"},"parameters":[{"in":"path","name":"id","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Positive integer resource id.","example":123},"required":true,"description":"Positive integer resource id."},{"in":"header","name":"Idempotency-Key","schema":{"type":"string","minLength":1,"maxLength":255,"description":"Unique key for this logical write operation."},"required":true,"description":"Unique key for this logical write operation."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"buyerName":{"type":"string","minLength":1,"maxLength":255},"buyerEmail":{"type":"string","maxLength":255,"format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"dueDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"expectedBaseline":{"type":"string","pattern":"^[a-f0-9]{64}$"},"reissue":{"type":"boolean"},"supersedesId":{"type":"integer","exclusiveMinimum":0,"maximum":2147483647}},"required":["buyerName","buyerEmail","dueDate","expectedBaseline"]}}}},"responses":{"200":{"description":"The order's already-open request; no new email is sent by this call.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"paymentRequest":{"$ref":"#/components/schemas/PaymentRequest"},"requests":{"type":"array","items":{"$ref":"#/components/schemas/PaymentRequest"},"description":"Every request this call created or returned, by profileId (several for a mixed basket); `paymentRequest` is the first of them."},"created":{"type":"boolean","description":"False when every group was already covered: the open requests were returned and no email was sent."}},"required":["paymentRequest","requests","created"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"201":{"description":"The issued request.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"paymentRequest":{"$ref":"#/components/schemas/PaymentRequest"},"requests":{"type":"array","items":{"$ref":"#/components/schemas/PaymentRequest"},"description":"Every request this call created or returned, by profileId (several for a mixed basket); `paymentRequest` is the first of them."},"created":{"type":"boolean","description":"False when every group was already covered: the open requests were returned and no email was sent."}},"required":["paymentRequest","requests","created"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The API key lacks write permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Order not found for this vendor.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"The baseline changed, or the request state moved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/orders/{id}/payment-request/settle":{"post":{"operationId":"settleOrderPaymentRequest","summary":"Mark an order's open payment request as paid.","description":"Requires a read_write key. The transfer arrived: a vendor_confirmed order becomes paid; a handed-over picked_up order records its payment. The receipt is queued and the request records paid_via=api with payment method wire_transfer. Body {} acts on the order's newest open request, else its newest (one per sales profile can be open, so on a mixed basket that may not be the profile you mean); pin {\"paymentRequestId\": n} for automated settlement, so another profile's request or one re-issued in between (with a different amount) is never settled by mistake. A request whose amount no longer matches its sales profile's share of the order (the order changed after it was issued) is refused with 409 request_stale and nothing is written: cancel it and issue a new one. Every refusal carries a code in `details.reason`: 404 not_found for order_not_found and request_not_found; 409 conflict for baseline_changed (with the current `details.baseline`), request_not_open and request_stale; 422 validation_error for the order preconditions; 429 rate_limited for send_limit_reached.","tags":["Orders"],"x-required-access":"write","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"orders"},"parameters":[{"in":"path","name":"id","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Positive integer resource id.","example":123},"required":true,"description":"Positive integer resource id."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"paymentRequestId":{"type":"integer","exclusiveMinimum":0,"maximum":2147483647}},"additionalProperties":false}}}},"responses":{"200":{"description":"The settled request.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PaymentRequest"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The API key lacks write permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Order not found for this vendor, it has no payment request, or the pinned paymentRequestId is not this order's.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"The payment request is not open (request_not_open), or its amount is out of date (request_stale).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/orders/{id}/payment-request/cancel":{"post":{"operationId":"cancelOrderPaymentRequest","summary":"Withdraw an order's open payment request.","description":"Requires a read_write key. Body {} acts on the order's newest open request, else its newest (one per sales profile can be open); {\"paymentRequestId\": n} pins one. The order itself usually does not change; a handed-over picked_up order keeps its pending payment. When the paid requests already cover every sales-profile group the order still has and their amounts add up to the order total, the withdrawal settles the order (a vendor_confirmed order becomes paid, a picked_up one records its payment) and queues its receipt. Every refusal carries a code in `details.reason`: 404 not_found for order_not_found and request_not_found; 409 conflict for baseline_changed (with the current `details.baseline`), request_not_open and request_stale; 422 validation_error for the order preconditions; 429 rate_limited for send_limit_reached.","tags":["Orders"],"x-required-access":"write","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"orders"},"parameters":[{"in":"path","name":"id","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Positive integer resource id.","example":123},"required":true,"description":"Positive integer resource id."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"paymentRequestId":{"type":"integer","exclusiveMinimum":0,"maximum":2147483647}},"additionalProperties":false}}}},"responses":{"200":{"description":"The withdrawn request.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PaymentRequest"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The API key lacks write permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Order not found for this vendor, it has no payment request, or the pinned paymentRequestId is not this order's.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"The payment request is not open.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/orders/{id}/payment-request/pdf":{"get":{"operationId":"getOrderPaymentRequestPdf","summary":"Download one of an order's payment requests as a PDF.","description":"Binary (application/pdf attachment), rendered from the frozen snapshot in the language it was sent in. `paymentRequestId` picks the request (one per sales profile, see `paymentRequests`); without it, the order's newest open request, else its newest. Rate-limited to 30 per minute per credential. Binary; use REST: an MCP tool call returns only a pointer to this REST route ({ binary, contentType, rest }), never the document.","tags":["Orders"],"x-required-access":"read","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"orders"},"parameters":[{"in":"path","name":"id","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Positive integer resource id.","example":123},"required":true,"description":"Positive integer resource id."},{"in":"query","name":"paymentRequestId","schema":{"description":"The request to download; it must belong to this order (else 404 request_not_found). Omitted: the order's newest open request, else its newest.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"example":123},"description":"The request to download; it must belong to this order (else 404 request_not_found). Omitted: the order's newest open request, else its newest."}],"responses":{"200":{"description":"The payment request PDF.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Order not found for this vendor, it has no payment request, or the paymentRequestId is not this order's.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/products":{"get":{"operationId":"listProducts","summary":"List products","description":"Returns the authenticated vendor's products, paginated, with optional search and tag filters.","tags":["Products"],"x-required-access":"read","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"products"},"parameters":[{"in":"query","name":"page","schema":{"default":1,"description":"1-based page number (max 1000).","example":1,"type":"integer","minimum":1,"maximum":1000},"description":"1-based page number (max 1000)."},{"in":"query","name":"pageSize","schema":{"default":20,"description":"Items per page (max 100).","example":20,"type":"integer","minimum":1,"maximum":100},"description":"Items per page (max 100)."},{"in":"query","name":"search","schema":{"description":"Case-insensitive product-name search.","example":"tomato","type":"string","maxLength":100},"description":"Case-insensitive product-name search."},{"in":"query","name":"tags","schema":{"description":"Filter by tag id, slug, or name. Comma-separated or repeated.","example":"organic,seasonal","type":"string"},"description":"Filter by tag id, slug, or name. Comma-separated or repeated."}],"responses":{"200":{"description":"A page of products.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductListResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"operationId":"createProduct","summary":"Create a product","description":"Creates a product for the authenticated vendor.","tags":["Products"],"x-required-access":"write","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"products"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string","maxLength":5000},"price":{"type":"number","exclusiveMinimum":0,"maximum":99999999.99},"unit":{"type":"string","minLength":1,"maxLength":20},"averageWeight":{"type":"number","exclusiveMinimum":0,"maximum":9999999.999},"isSoldByWeight":{"type":"boolean"},"preparationDays":{"type":"integer","minimum":0,"maximum":30},"vatRate":{"type":"string","enum":["5","27","AAM"]},"options":{"type":"object","propertyNames":{"type":"string","maxLength":100},"additionalProperties":{"type":"object","properties":{"choices":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":100}},"price_modifier":{"type":"object","propertyNames":{"type":"string","maxLength":100},"additionalProperties":{"type":"number","minimum":-1000000,"maximum":1000000}},"preparation_days":{"type":"integer","minimum":0,"maximum":30},"is_required":{"type":"boolean"},"minimum_selection":{"anyOf":[{"type":"number","const":0},{"type":"number","const":1}]},"maximum_selection":{"type":"number","const":1}},"required":["choices"]}},"status":{"type":"string","enum":["draft","active","discontinued"]},"tagIds":{"maxItems":20,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"},"uniqueItems":true}},"required":["name","price","unit"],"additionalProperties":false}}}},"responses":{"201":{"description":"The created product.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"API key lacks write permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/products/{id}":{"get":{"operationId":"getProduct","summary":"Get a product","description":"Returns a single product owned by the authenticated vendor.","tags":["Products"],"x-required-access":"read","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"products"},"parameters":[{"in":"path","name":"id","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Positive integer resource id.","example":123},"required":true,"description":"Positive integer resource id."}],"responses":{"200":{"description":"The product.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Product not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"operationId":"updateProduct","summary":"Update a product","description":"Updates fields of a product owned by the authenticated vendor.","tags":["Products"],"x-required-access":"write","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"products"},"parameters":[{"in":"path","name":"id","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Positive integer resource id.","example":123},"required":true,"description":"Positive integer resource id."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string","maxLength":5000},"price":{"type":"number","exclusiveMinimum":0,"maximum":99999999.99},"unit":{"type":"string","minLength":1,"maxLength":20},"averageWeight":{"type":"number","exclusiveMinimum":0,"maximum":9999999.999},"isSoldByWeight":{"type":"boolean"},"preparationDays":{"type":"integer","minimum":0,"maximum":30},"vatRate":{"type":"string","enum":["5","27","AAM"]},"options":{"type":"object","propertyNames":{"type":"string","maxLength":100},"additionalProperties":{"type":"object","properties":{"choices":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":100}},"price_modifier":{"type":"object","propertyNames":{"type":"string","maxLength":100},"additionalProperties":{"type":"number","minimum":-1000000,"maximum":1000000}},"preparation_days":{"type":"integer","minimum":0,"maximum":30},"is_required":{"type":"boolean"},"minimum_selection":{"anyOf":[{"type":"number","const":0},{"type":"number","const":1}]},"maximum_selection":{"type":"number","const":1}},"required":["choices"]}},"status":{"type":"string","enum":["draft","active","discontinued"]},"isHidden":{"type":"boolean"},"tagIds":{"maxItems":20,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"},"uniqueItems":true}},"additionalProperties":false,"minProperties":1}}}},"responses":{"200":{"description":"The updated product.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"API key lacks write permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Product not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"operationId":"deleteProduct","summary":"Delete a product","description":"Soft-deletes a product owned by the authenticated vendor and cancels its active supplies.","tags":["Products"],"x-required-access":"write","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"products"},"parameters":[{"in":"path","name":"id","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Positive integer resource id.","example":123},"required":true,"description":"Positive integer resource id."}],"responses":{"204":{"description":"Product deleted."},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"API key lacks write permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Product not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/reviews":{"get":{"operationId":"listReviews","summary":"List reviews","description":"Returns the authenticated vendor's visible vendor and product reviews. Results are ordered by updatedAt descending, then id descending.","tags":["Reviews"],"x-required-access":"read","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"reviews"},"parameters":[{"in":"query","name":"page","schema":{"default":1,"description":"1-based page number (max 1000).","example":1,"type":"integer","minimum":1,"maximum":1000},"description":"1-based page number (max 1000)."},{"in":"query","name":"pageSize","schema":{"default":20,"description":"Items per page (max 100).","example":20,"type":"integer","minimum":1,"maximum":100},"description":"Items per page (max 100)."},{"in":"query","name":"orderId","schema":{"description":"Only return reviews submitted for this order.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"example":123},"description":"Only return reviews submitted for this order."},{"in":"query","name":"kind","schema":{"description":"Only return vendor or product reviews.","type":"string","enum":["vendor","product"]},"description":"Only return vendor or product reviews."},{"in":"query","name":"updatedAfter","schema":{"description":"Only return reviews updated strictly after this ISO-8601 timestamp.","example":"2026-08-01T00:00:00Z","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},"description":"Only return reviews updated strictly after this ISO-8601 timestamp."}],"responses":{"200":{"description":"A page of reviews.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewListResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/reviews/{id}":{"get":{"operationId":"getReview","summary":"Get a review","description":"Returns one visible review owned by the authenticated vendor. Hidden, foreign, and unknown ids all resolve to 404.","tags":["Reviews"],"x-required-access":"read","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"reviews"},"parameters":[{"in":"path","name":"id","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Positive integer resource id.","example":123},"required":true,"description":"Positive integer resource id."}],"responses":{"200":{"description":"The review.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Review not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/supplies":{"get":{"operationId":"listSupplies","summary":"List supplies","description":"Returns the authenticated vendor's supply windows, paginated, filterable by tab, product, and date range.","tags":["Supplies"],"x-required-access":"read","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"supplies"},"parameters":[{"in":"query","name":"page","schema":{"default":1,"description":"1-based page number (max 1000).","example":1,"type":"integer","minimum":1,"maximum":1000},"description":"1-based page number (max 1000)."},{"in":"query","name":"pageSize","schema":{"default":20,"description":"Items per page (max 100).","example":20,"type":"integer","minimum":1,"maximum":100},"description":"Items per page (max 100)."},{"in":"query","name":"tab","schema":{"default":"active","description":"Which supplies to list.","example":"active","type":"string","enum":["active","expired","deactivated"]},"description":"Which supplies to list."},{"in":"query","name":"productId","schema":{"description":"Filter by product id.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"example":123},"description":"Filter by product id."},{"in":"query","name":"dateFrom","schema":{"description":"Filter to windows ending on/after this date (YYYY-MM-DD).","example":"2026-06-01","type":"string"},"description":"Filter to windows ending on/after this date (YYYY-MM-DD)."},{"in":"query","name":"dateTo","schema":{"description":"Filter to windows starting on/before this date (YYYY-MM-DD).","example":"2026-06-30","type":"string"},"description":"Filter to windows starting on/before this date (YYYY-MM-DD)."}],"responses":{"200":{"description":"A page of supplies.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplyListResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"operationId":"createSupply","summary":"Create a supply","description":"Creates a supply window for one of the authenticated vendor's products. With `selectedOptions` the row is a produced form row serving exactly that option combination (validated against the product's current options; key order is not part of the identity); without it, a product-level base pool. An orderable base pool and a form row must never overlap in time, and two supplies of the same product+variant must never overlap.","tags":["Supplies"],"x-required-access":"write","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"supplies"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"productId":{"type":"integer","exclusiveMinimum":0,"maximum":2147483647,"description":"Owning product id."},"quantity":{"type":"integer","minimum":0,"maximum":999999,"description":"Stock for this window. 0 is allowed: it publishes the window as a placeholder while the figure is unknown, and buyers see the product as sold out until it is raised.","example":40},"availableFrom":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$","description":"ISO-8601 start of the supply window.","example":"2026-06-01T08:00:00Z"},"availableUntil":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$","description":"ISO-8601 end of the supply window.","example":"2026-06-08T18:00:00Z"},"selectedOptions":{"description":"Exact option combination this supply serves (produced form row). Omit or null for a product-level base pool. Group names and choices must exactly match the product's current options definition.","example":{"Csomag:":"Darabolt, vákumcsomagolt"},"anyOf":[{"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":100},"additionalProperties":{"type":"string","minLength":1,"maxLength":200}},{"type":"null"}]}},"required":["productId","quantity","availableFrom","availableUntil"]}}}},"responses":{"201":{"description":"The created supply.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplyResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"API key lacks write permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Product not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/supplies/production-close":{"post":{"operationId":"closeProduction","summary":"Close a production batch","description":"Atomic base-pool → produced-form transition for the weekly batch. Creates the produced form rows (window inherited from the base supply), moves every awaiting reservation onto its exactly-matching form (jsonb-equal `selectedOptions`), reports shortfalls (produced < reserved) and orphans (forms with reservations but no production), and closes the base: drained → `cancelled`; still holding orphans → residual `closed` row. Re-running against the residual row moves later-produced orphans. With `producedQuantity` instead of `variants`, marks the base row itself produced (products without option forms). Produced stock is exempt from preparation-time gating on every ordering surface. The Idempotency-Key header is REQUIRED.","tags":["Supplies"],"x-required-access":"write","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"supplies"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"productId":{"type":"integer","exclusiveMinimum":0,"maximum":2147483647,"description":"Owning product id."},"baseSupplyId":{"description":"The base pool (or closed residual) to transition. Form rows inherit ITS window; window fields are forbidden when set.","type":"integer","exclusiveMinimum":0,"maximum":2147483647},"availableFrom":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$","description":"ISO-8601 start of the supply window.","example":"2026-06-01T08:00:00Z"},"availableUntil":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$","description":"ISO-8601 end of the supply window.","example":"2026-06-08T18:00:00Z"},"variants":{"description":"Produced forms with their absolute quantities.","minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"selectedOptions":{"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":100},"additionalProperties":{"type":"string","minLength":1,"maxLength":200},"description":"Exact option combination of the produced form; must match the product's current options definition.","example":{"Csomag:":"Darabolt, vákumcsomagolt"}},"quantity":{"type":"integer","minimum":0,"maximum":999999,"description":"Absolute produced quantity of this form (not an increment).","example":40}},"required":["selectedOptions","quantity"]}},"producedQuantity":{"description":"Alternative to `variants` (requires `baseSupplyId`): the whole batch was produced without form splitting — mark the base row produced with this absolute quantity.","type":"integer","minimum":0,"maximum":999999,"example":40}},"required":["productId"]}}}},"responses":{"200":{"description":"The transition result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductionCloseResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"API key lacks write permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Product or base supply not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/supplies/forecast":{"get":{"operationId":"getSupplyForecast","summary":"Supply forecast","description":"Supply forecasting for the authenticated vendor: per-product consumption trends (trailing 12 weekly + 6 monthly buckets), event restock suggestions (average per-event sales × upcoming joined events vs current net available, most urgent first), and seasonal patterns (monthly averages for products with 3+ months of history). Computed from completed orders and active supply windows. Takes no query params.","tags":["Supplies"],"x-required-access":"read","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"supplies"},"responses":{"200":{"description":"The supply forecast.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplyForecastResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/supplies/{id}":{"get":{"operationId":"getSupply","summary":"Get a supply","description":"Returns a single supply owned by the authenticated vendor.","tags":["Supplies"],"x-required-access":"read","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"supplies"},"parameters":[{"in":"path","name":"id","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Positive integer resource id.","example":123},"required":true,"description":"Positive integer resource id."}],"responses":{"200":{"description":"The supply.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplyResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Supply not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"operationId":"updateSupply","summary":"Update a supply","description":"Updates the quantity and/or time window of an active supply owned by the authenticated vendor. The variant identity (`selectedOptions`) is immutable — sending it is rejected with 422; create a new supply for another variant. The absolute `quantity` can never drop below `reserved`.","tags":["Supplies"],"x-required-access":"write","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"supplies"},"parameters":[{"in":"path","name":"id","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Positive integer resource id.","example":123},"required":true,"description":"Positive integer resource id."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"quantity":{"type":"integer","minimum":0,"maximum":999999,"description":"Stock for this window. 0 is allowed: it publishes the window as a placeholder while the figure is unknown, and buyers see the product as sold out until it is raised.","example":40},"availableFrom":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$","description":"ISO-8601 start of the supply window.","example":"2026-06-01T08:00:00Z"},"availableUntil":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$","description":"ISO-8601 end of the supply window.","example":"2026-06-08T18:00:00Z"},"selectedOptions":{"description":"Immutable. Sending this field is rejected with 422 validation_error — create a new supply for another variant."}}}}}},"responses":{"200":{"description":"The updated supply.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplyResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"API key lacks write permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Supply not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"operationId":"deleteSupply","summary":"Cancel a supply","description":"Cancels an active supply owned by the authenticated vendor. Blocked while the supply has reservations.","tags":["Supplies"],"x-required-access":"write","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"supplies"},"parameters":[{"in":"path","name":"id","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Positive integer resource id.","example":123},"required":true,"description":"Positive integer resource id."}],"responses":{"200":{"description":"The cancelled supply id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplyDeleteResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"API key lacks write permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Supply not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/support/accounts/by-email":{"get":{"operationId":"supportLookupAccountByEmail","summary":"Support: does an account exist for this email, and in what state? (support key)","description":"Support key only (ADR-038): an API key with the explicit `support` scope, minted by a platform admin; every vendor key and OAuth token gets 403. Matches case-insensitively; an unknown address is a 200 with `exists: false`. Returns ids, names and booleans only — never credentials or tokens.","tags":["Support"],"x-required-access":"read","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"support","support":true},"x-required-authority":"support","parameters":[{"in":"query","name":"email","schema":{"type":"string","maxLength":255,"format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"required":true}],"responses":{"200":{"description":"The account state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportAccountLookupResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Not a support key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/support/community-markets/{idOrSlug}":{"get":{"operationId":"supportGetCommunityMarket","summary":"Support: state of one community market by id or slug (support key)","description":"Support key only (ADR-038): an API key with the explicit `support` scope, minted by a platform admin; every vendor key and OAuth token gets 403. Status, phase, supporters, organizer and whether that organizer is listed on the linked location, follower count, first market day and announcement.","tags":["Support"],"x-required-access":"read","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"support","support":true},"x-required-authority":"support","parameters":[{"in":"path","name":"idOrSlug","schema":{"type":"string","description":"Numeric community-market id or its slug.","example":"88"},"required":true,"description":"Numeric community-market id or its slug."}],"responses":{"200":{"description":"The community market state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportCommunityMarketStateResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Not a support key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Community market not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/support/community-markets/{idOrSlug}/activate":{"post":{"operationId":"supportActivateCommunityMarket","summary":"Support: activate a community market, as the admin button does (support key)","description":"Support key only (ADR-038): an API key with the explicit `support` scope, minted by a platform admin; every vendor key and OAuth token gets 403. Requires read_write and Idempotency-Key. Same core as the admin \"Aktiválás\" button: reuses the live linked location or creates one, turns supporters into followers, and emails them (in the market's language) unless `notifySupporters` is false. Optional `locationId` links the market to an existing live location instead of creating one. Only `active` and `threshold_reached` markets activate. Audited to the key's admin.","tags":["Support"],"x-required-access":"write","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"support","support":true},"x-required-authority":"support","parameters":[{"in":"path","name":"idOrSlug","schema":{"type":"string","description":"Numeric community-market id or its slug.","example":"88"},"required":true,"description":"Numeric community-market id or its slug."},{"in":"header","name":"Idempotency-Key","schema":{"type":"string","minLength":1,"maxLength":255,"description":"Unique key for this logical write operation."},"required":true,"description":"Unique key for this logical write operation."}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportActivateCommunityMarketBody"}}}},"responses":{"200":{"description":"Activated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportActivateCommunityMarketResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Not a read_write support key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Community market not found, or `locationId` names no live location (`details.reason: location_not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Already activated or closed (`details` carries the current state), or the market is linked to a different live location than `locationId` (`details.reason: location_conflict`, `details.linkedLocationId`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/support/locations/{id}":{"get":{"operationId":"supportGetLocation","summary":"Support: a location's organizers, upcoming market days and community markets (support key)","description":"Support key only (ADR-038): an API key with the explicit `support` scope, minted by a platform admin; every vendor key and OAuth token gets 403. Any location, soft-deleted ones flagged. Organizers are the ADR-037 list; upcoming market days include hidden ones and their vendors.","tags":["Support"],"x-required-access":"read","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"support","support":true},"x-required-authority":"support","parameters":[{"in":"path","name":"id","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Positive integer resource id.","example":123},"required":true,"description":"Positive integer resource id."}],"responses":{"200":{"description":"The location overview.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportLocationResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Not a support key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Location not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/support/locations/{id}/organizers":{"post":{"operationId":"supportAddLocationOrganizer","summary":"Support: invite an existing account to co-organize a location, by email (support key)","description":"Support key only (ADR-038): an API key with the explicit `support` scope, minted by a platform admin; every vendor key and OAuth token gets 403. Requires read_write. Same rules and invitation email as the admin dashboard: the account becomes an organizer only after it accepts. Add-only (201 with `invited: true` for a new or renewed invitation, 200 with `invited: false` when already listed). Audited to the key's admin.","tags":["Support"],"x-required-access":"write","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"support","support":true},"x-required-authority":"support","parameters":[{"in":"path","name":"id","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Positive integer resource id.","example":123},"required":true,"description":"Positive integer resource id."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","maxLength":255,"format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"required":["email"]}}}},"responses":{"200":{"description":"Already listed; nothing changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportAddOrganizerResponse"}}}},"201":{"description":"Invitation created or renewed; pending until accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportAddOrganizerResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Not a read_write support key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Location not found, or no live account for the email.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"The account is a market helper.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/support/locations/{id}/events":{"post":{"operationId":"supportCreateMarketDays","summary":"Support: create market days at a location, optionally with vendors (support key)","description":"Support key only (ADR-038): an API key with the explicit `support` scope, minted by a platform admin; every vendor key and OAuth token gets 403. Requires read_write and Idempotency-Key. Atomic batch equivalent to the admin create-event + add-vendor actions, including cache revalidation and the follower \"new vendor\" notification. Offset-less times are Europe/Budapest wall-clock. Audited to the key's admin.","tags":["Support"],"x-required-access":"write","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"support","support":true},"x-required-authority":"support","parameters":[{"in":"path","name":"id","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Positive integer resource id.","example":123},"required":true,"description":"Positive integer resource id."},{"in":"header","name":"Idempotency-Key","schema":{"type":"string","minLength":1,"maxLength":255,"description":"Unique key for this logical write operation."},"required":true,"description":"Unique key for this logical write operation."}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportCreateMarketDaysBody"}}}},"responses":{"201":{"description":"The created market days.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportCreateMarketDaysResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Not a read_write support key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Location or vendor not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/tags":{"get":{"operationId":"listTags","summary":"List product tags","description":"Returns the taxonomy tag catalogue. Use the returned ids in product `tagIds` fields.","tags":["Tags"],"x-required-access":"read","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"tags"},"responses":{"200":{"description":"The product tag catalogue, ordered by name.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagListResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/webhooks":{"get":{"operationId":"listWebhookEndpoints","summary":"List webhook endpoints","description":"Returns the authenticated vendor's outbound webhook endpoints, newest first, with masked signing secrets. The raw secret is never listable.","tags":["Webhooks"],"x-required-access":"read","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"webhooks"},"responses":{"200":{"description":"The vendor's webhook endpoints.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookListResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"operationId":"createWebhookEndpoint","summary":"Create a webhook endpoint","description":"Registers an HTTPS endpoint subscribed to the given event types. The URL is SSRF-guarded at save time and re-resolved at send time. Subscribing to an event requires the resource scope that owns it (`order.*` → `orders`, `supply.*` → `supplies`, `event.*` → `events`). The response carries the raw `whsec_…` signing secret exactly once — store it immediately. NOTE for MCP callers: that secret is returned in the tool result and therefore enters the model's context and any persisted transcript; prefer the REST surface when the secret must not be exposed to the agent.","tags":["Webhooks"],"x-required-access":"write","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"webhooks"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":2048,"format":"uri","description":"HTTPS destination URL (at most 2048 characters). SSRF-guarded: private/loopback/link-local/ULA/CGNAT/metadata addresses are rejected.","example":"https://pos.example.com/webhooks/villampiac"},"enabledEvents":{"minItems":1,"type":"array","items":{"type":"string","enum":["order.created","order.state_changed","order.updated","supply.low","event.reminder","review.submitted"]},"description":"Event types to subscribe to (at least one, each at most once).","example":["order.created","order.state_changed"],"uniqueItems":true}},"required":["url","enabledEvents"]}}}},"responses":{"201":{"description":"The created endpoint plus its one-time raw signing secret.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCreateResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"API key lacks write permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/webhooks/{id}/rotate-secret":{"post":{"operationId":"rotateWebhookEndpointSecret","summary":"Rotate a webhook endpoint's signing secret","description":"Replaces the endpoint's signing secret; the previous secret stops verifying as soon as this call commits. The response carries the new raw `whsec_…` secret exactly once — store it immediately. A foreign id resolves to 404. NOTE for MCP callers: that secret is returned in the tool result and therefore enters the model's context and any persisted transcript; prefer the REST surface when the secret must not be exposed to the agent.","tags":["Webhooks"],"x-required-access":"write","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"webhooks"},"parameters":[{"in":"path","name":"id","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Positive integer resource id.","example":123},"required":true,"description":"Positive integer resource id."}],"responses":{"200":{"description":"The endpoint plus its new one-time raw signing secret.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCreateResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"API key lacks write permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Webhook endpoint not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/webhooks/{id}":{"delete":{"operationId":"deleteWebhookEndpoint","summary":"Delete a webhook endpoint","description":"Hard-deletes an endpoint owned by the authenticated vendor, cascading its delivery log. A foreign id resolves to 404.","tags":["Webhooks"],"x-required-access":"write","x-principal-kind":"vendor","x-operation-authority":{"kind":"vendor","scope":"webhooks"},"parameters":[{"in":"path","name":"id","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Positive integer resource id.","example":123},"required":true,"description":"Positive integer resource id."}],"responses":{"200":{"description":"The deleted endpoint id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeleteResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"API key lacks write permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Webhook endpoint not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}},"components":{"schemas":{"SupportActivateCommunityMarketBody":{"type":"object","properties":{"notifySupporters":{"description":"Email the supporters that the market is live, as the admin button does. Default true; false schedules no email.","type":"boolean"},"locationId":{"description":"Activate onto this existing live location instead of creating one (an organizer already runs the place). Demand and followers move to it and `locationReused` is true. 404 when it does not exist or is deleted; 409 when the market is already linked to a different live location. Omit for the default: the market's linked location, else a new one.","example":95,"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}}},"SupportCreateMarketDaysBody":{"type":"object","properties":{"events":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"startTime":{"type":"string","description":"ISO-8601 with an explicit offset (`2026-10-30T08:00:00+01:00`, `…Z`) taken literally, or Europe/Budapest wall-clock time without one (`2026-10-30T08:00`). Wall-clock times inside a DST gap or overlap are rejected; send an offset.","example":"2026-10-30T08:00"},"endTime":{"type":"string","description":"ISO-8601 with an explicit offset (`2026-10-30T08:00:00+01:00`, `…Z`) taken literally, or Europe/Budapest wall-clock time without one (`2026-10-30T08:00`). Wall-clock times inside a DST gap or overlap are rejected; send an offset.","example":"2026-10-30T08:00"}},"required":["startTime","endTime"]},"description":"Each window must start in the future and end after it starts."},"vendorIds":{"description":"Vendors attached to every created market day (deduplicated).","maxItems":20,"type":"array","items":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"hidden":{"description":"Create the market days hidden. Default false.","type":"boolean"}},"required":["events"]},"AnalyticsResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AnalyticsData"}},"required":["data"],"additionalProperties":false},"AnalyticsData":{"type":"object","properties":{"from":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$","description":"Resolved range start (ISO-8601 UTC).","example":"2026-01-01T00:00:00.000Z"},"to":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$","description":"Resolved range end (ISO-8601 UTC).","example":"2026-01-31T00:00:00.000Z"},"revenue":{"type":"string","description":"Total paid revenue over the range, as a decimal string.","example":"45231.00"},"orderCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total paid orders over the range.","example":128},"byDay":{"type":"array","items":{"$ref":"#/components/schemas/AnalyticsDayBucket"},"description":"Per-day paid revenue and order counts, ascending."},"byState":{"type":"array","items":{"$ref":"#/components/schemas/AnalyticsStateBucket"},"description":"Order counts grouped by state (excluding carts)."}},"required":["from","to","revenue","orderCount","byDay","byState"],"additionalProperties":false},"AnalyticsDayBucket":{"type":"object","properties":{"date":{"type":"string","description":"UTC day (YYYY-MM-DD).","example":"2026-01-15"},"revenue":{"type":"string","description":"Paid revenue for the day, as a decimal string.","example":"1234.50"},"orderCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Paid orders placed on the day.","example":7}},"required":["date","revenue","orderCount"],"additionalProperties":false},"AnalyticsStateBucket":{"type":"object","properties":{"state":{"type":"string","description":"Order state.","example":"paid"},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of orders in this state.","example":12}},"required":["state","count"],"additionalProperties":false},"ErrorEnvelope":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Developer-facing English message."},"details":{},"requestId":{"type":"string","description":"Echoes the `x-request-id` header."}},"required":["code","message","requestId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"description":"Standard error response envelope."},"ErrorCode":{"type":"string","enum":["unauthorized","invalid_api_key","insufficient_permission","not_found","conflict","validation_error","idempotency_conflict","rate_limited","internal_error"],"description":"Stable, machine-readable error code."},"CustomerCrmResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CustomerCrm"}},"required":["data"],"additionalProperties":false},"CustomerCrm":{"type":"object","properties":{"email":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$","example":"buyer@example.com"},"stats":{"$ref":"#/components/schemas/CustomerCrmStats"},"reliability":{"$ref":"#/components/schemas/CustomerCrmReliability"},"preferences":{"$ref":"#/components/schemas/CustomerCrmPreferences"},"lastOrder":{"$ref":"#/components/schemas/CustomerCrmLastOrder"}},"required":["email","stats","reliability","preferences","lastOrder"],"additionalProperties":false},"CustomerCrmStats":{"type":"object","properties":{"lifetimeValue":{"type":"string","description":"Sum of this customer's paid and picked-up order totals with the authenticated vendor, as a decimal string.","example":"45200.00"},"currency":{"type":"string","description":"Currency of the monetary figures.","example":"HUF"},"completedOrderCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of paid or picked-up orders.","example":12},"averageOrderValue":{"type":"string","description":"Lifetime value divided by the completed order count, as a decimal string.","example":"3766.67"},"firstOrderAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},{"type":"null"}],"description":"When the customer first ordered from this vendor (any non-cart order).","example":"2025-03-01T10:00:00.000Z"},"lastOrderAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},{"type":"null"}],"description":"When the customer last ordered from this vendor (any non-cart order, including cancelled ones — this measures activity, not revenue).","example":"2026-07-28T09:30:00.000Z"}},"required":["lifetimeValue","currency","completedOrderCount","averageOrderValue","firstOrderAt","lastOrderAt"],"additionalProperties":false},"CustomerCrmReliability":{"type":"object","properties":{"noShowCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Orders the customer never picked up.","example":1},"cancelledCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Orders the customer themselves cancelled. Excludes vendor cancellations and rejections, and the cancellations written by event moves or account deletion.","example":0},"rating":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The authenticated vendor's own rating of this customer (`trusted`, `neutral`, `negative`), or null when they never rated them.","example":"trusted"},"trustScore":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Cross-vendor rating tally (trusted minus negative). Null when the address has no registered account.","example":3}},"required":["noShowCount","cancelledCount","rating","trustScore"],"additionalProperties":false},"CustomerCrmPreferences":{"type":"object","properties":{"topProducts":{"type":"array","items":{"$ref":"#/components/schemas/CustomerCrmTopProduct"},"description":"Up to five most-bought products, by total quantity across completed orders."},"topLocation":{"anyOf":[{"type":"object","properties":{"locationId":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"example":3},"name":{"type":"string","example":"Fény Street Market"}},"required":["locationId","name"],"additionalProperties":false},{"type":"null"}],"description":"The pickup location the customer collects from most often, or null when no completed order has one."}},"required":["topProducts","topLocation"],"additionalProperties":false},"CustomerCrmTopProduct":{"type":"object","properties":{"productId":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"example":12},"name":{"type":"string","example":"Sourdough loaf"},"totalQuantity":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Units bought across all completed orders.","example":8}},"required":["productId","name","totalQuantity"],"additionalProperties":false},"CustomerCrmLastOrder":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"example":123},"number":{"anyOf":[{"type":"string"},{"type":"null"}],"example":"VO-2026-000123"},"state":{"type":"string","example":"picked_up"},"total":{"type":"string","description":"Order total as a decimal string.","example":"3500.00"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$","example":"2026-07-28T09:30:00.000Z"}},"required":["id","number","state","total","createdAt"],"additionalProperties":false},"CustomerCrmByPhoneResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CustomerCrmByPhone"}},"required":["data"],"additionalProperties":false},"CustomerCrmByPhone":{"type":"object","properties":{"phone":{"type":"string","pattern":"^\\d{6,15}$","description":"The customer's phone number as matched, digits only (formatting characters are stripped before lookup).","example":"36301234567"},"stats":{"$ref":"#/components/schemas/CustomerCrmStats"},"reliability":{"$ref":"#/components/schemas/CustomerCrmReliability"},"preferences":{"$ref":"#/components/schemas/CustomerCrmPreferences"},"lastOrder":{"$ref":"#/components/schemas/CustomerCrmLastOrder"}},"required":["phone","stats","reliability","preferences","lastOrder"],"additionalProperties":false},"DemandIntelligenceResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DemandIntelligenceData"}},"required":["data"],"additionalProperties":false},"DemandIntelligenceData":{"type":"object","properties":{"generatedAt":{"type":"string","description":"ISO-8601 UTC generation timestamp.","example":"2026-08-01T10:00:00.000Z"},"unservedSearchCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Nearby demand items no interested vendor fulfills yet.","example":12},"nearbyDemandCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Nearby demand items matching the vendor's products.","example":7},"categoryDemand":{"type":"array","items":{"$ref":"#/components/schemas/DemandIntelligenceCategory"},"description":"Top demand categories near the anchor (up to 20, most demanded first)."},"eventRecommendations":{"type":"array","items":{"$ref":"#/components/schemas/DemandIntelligenceEventRecommendation"},"description":"Upcoming events near the anchor with matching demand (up to 10, soonest first)."},"supplyForecasts":{"type":"array","items":{"$ref":"#/components/schemas/DemandIntelligenceSupplyForecast"},"description":"Per-product restock projection for the vendor's upcoming joined events."}},"required":["generatedAt","unservedSearchCount","nearbyDemandCount","categoryDemand","eventRecommendations","supplyForecasts"],"additionalProperties":false},"DemandIntelligenceCategory":{"type":"object","properties":{"category":{"type":"string","description":"Lowercased demand item name buyers asked for.","example":"sourdough"},"searchCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Demand items for this category near the anchor.","example":9},"fulfilledRate":{"type":"string","description":"Decimal string: \"1.000\" when the vendor sells this category, otherwise \"0.000\".","example":"0.000"}},"required":["category","searchCount","fulfilledRate"],"additionalProperties":false},"DemandIntelligenceEventRecommendation":{"type":"object","properties":{"eventId":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"example":55},"locationName":{"type":"string","example":"Gödöllő Piac"},"startTime":{"type":"string","description":"ISO-8601 UTC event start.","example":"2026-08-08T06:00:00.000Z"},"demandScore":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Distinct nearby supporters whose demand matches the vendor's products around this event.","example":21},"reason":{"type":"string","description":"Comma-separated matched categories behind the score (empty when none).","example":"sourdough, goat cheese"}},"required":["eventId","locationName","startTime","demandScore","reason"],"additionalProperties":false},"DemandIntelligenceSupplyForecast":{"type":"object","properties":{"productId":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"example":77},"productName":{"type":"string","example":"Sourdough loaf"},"expectedDemand":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Suggested total stock for the vendor's upcoming joined events (rounded up).","example":43},"available":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Units available in currently active supply windows.","example":10},"suggestedAdditionalQuantity":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Additional units to stock (expected minus available, floored at 0).","example":33}},"required":["productId","productName","expectedDemand","available","suggestedAdditionalQuantity"],"additionalProperties":false},"EventListItem":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"startTime":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO-8601 UTC start."},"endTime":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO-8601 UTC end."},"isJoined":{"type":"boolean","description":"Whether this vendor has checked in."},"orderCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"This vendor's active orders at the event."},"vendorCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total vendors at the event."},"location":{"type":"object","properties":{"name":{"type":"string"},"address":{"type":"string"},"accessMode":{"type":"string","description":"Location access mode (open | restricted | private).","example":"open"},"isApproved":{"type":"boolean","description":"Whether this vendor is approved to join the location."}},"required":["name","address","accessMode","isApproved"],"additionalProperties":false}},"required":["id","startTime","endTime","isJoined","orderCount","vendorCount","location"],"additionalProperties":false,"description":"An event in the vendor's list view."},"PaginationMeta":{"type":"object","properties":{"page":{"type":"integer","minimum":1,"maximum":9007199254740991},"pageSize":{"type":"integer","minimum":1,"maximum":9007199254740991},"total":{"type":"integer","minimum":0,"maximum":9007199254740991},"totalPages":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["page","pageSize","total","totalPages"],"additionalProperties":false,"description":"Page-based pagination metadata."},"CreatedEvent":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"locationId":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"startTime":{"type":"string","description":"ISO-8601 UTC start.","example":"2026-08-01T06:00:00.000Z"},"endTime":{"type":"string","description":"ISO-8601 UTC end.","example":"2026-08-01T12:00:00.000Z"},"hidden":{"type":"boolean","description":"Hidden events stay invisible to vendors and the public until published from the manager UI."},"createdAt":{"type":"string","description":"ISO-8601 UTC."}},"required":["id","locationId","startTime","endTime","hidden","createdAt"],"additionalProperties":false,"description":"An event created or updated via the API."},"EventDetail":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"startTime":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO-8601 UTC start."},"endTime":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO-8601 UTC end."},"isJoined":{"type":"boolean"},"location":{"type":"object","properties":{"name":{"type":"string"},"address":{"type":"string"}},"required":["name","address"],"additionalProperties":false},"orders":{"type":"array","items":{"$ref":"#/components/schemas/EventDetailOrder"}}},"required":["id","startTime","endTime","isJoined","location","orders"],"additionalProperties":false,"description":"One event with this vendor's orders."},"EventDetailOrder":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"number":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"type":"string"},"total":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Decimal as string."},"paymentState":{"type":"string"},"paymentMethod":{"anyOf":[{"type":"string"},{"type":"null"}]},"note":{"anyOf":[{"type":"string"},{"type":"null"}]},"vendorNote":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO-8601 UTC."},"customer":{"type":"object","properties":{"firstName":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastName":{"anyOf":[{"type":"string"},{"type":"null"}]},"publicId":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string"},{"type":"null"}]},"isNew":{"type":"boolean","description":"First-time customer for this vendor."}},"required":["firstName","lastName","publicId","email","phone","isNew"],"additionalProperties":false},"items":{"type":"array","items":{"$ref":"#/components/schemas/EventDetailOrderItem"}}},"required":["id","number","state","total","paymentState","paymentMethod","note","vendorNote","createdAt","customer","items"],"additionalProperties":false,"description":"An order this vendor holds at the event."},"EventDetailOrderItem":{"type":"object","properties":{"productName":{"type":"string"},"quantity":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Ordered piece/package count. For weight-sold products this is not kilograms."},"lineTotal":{"type":"string","description":"Decimal string rounded line total computed by the server. Use this for revenue, reporting, and reconciliation."},"unitPrice":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Decimal string display unit price. For weight-sold products this is the kilogram price plus any selected per-piece option modifier."},"optionModifier":{"type":"string","description":"Decimal string per-piece option price delta included in unitPrice."},"unit":{"anyOf":[{"type":"string"},{"type":"null"}]},"selectedOptions":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},{"type":"null"}]},"weightGrams":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Measured total weight in grams for weight-sold items, otherwise null."},"isSoldByWeight":{"type":"boolean","description":"True when this item is priced by weight."},"averageWeight":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Decimal string average package weight in kilograms; used for estimated weight-sold totals when weightGrams is not set."}},"required":["productName","quantity","lineTotal","unitPrice","optionModifier","unit","selectedOptions","weightGrams","isSoldByWeight","averageWeight"],"additionalProperties":false,"description":"A line item on an event order."},"DeletedEvent":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"deleted":{"type":"boolean","const":true}},"required":["id","deleted"],"additionalProperties":false,"description":"The id of a deleted event."},"EventMembershipResult":{"type":"object","properties":{"eventId":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"joined":{"type":"boolean","description":"True after check-in, false after check-out."}},"required":["eventId","joined"],"additionalProperties":false,"description":"Result of a check-in/check-out."},"ManagedLocationListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ManagedLocation"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"],"additionalProperties":false},"ManagedLocation":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"example":12},"slug":{"type":"string","example":"godollo-piac"},"name":{"type":"string"},"address":{"type":"string"},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code.","example":"HU"},"accessMode":{"type":"string","description":"Location access mode (open | restricted | private).","example":"open"},"upcomingEventCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Events starting from now, including hidden ones (manager-dashboard parity)."}},"required":["id","slug","name","address","city","countryCode","accessMode","upcomingEventCount"],"additionalProperties":false,"description":"A location managed by the API key's creator."},"ManagedLocationDetail":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"example":12},"slug":{"type":"string","example":"godollo-piac"},"name":{"type":"string"},"address":{"type":"string"},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code.","example":"HU"},"filterTags":{"type":"array","items":{"type":"string"}},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"latitude":{"anyOf":[{"type":"number"},{"type":"null"}]},"longitude":{"anyOf":[{"type":"number"},{"type":"null"}]},"accessMode":{"type":"string","enum":["open","restricted"],"description":"Location access mode.","example":"open"},"vendorDescription":{"anyOf":[{"type":"string"},{"type":"null"}]},"upcomingEventCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Events starting from now, including hidden ones (manager-dashboard parity)."},"approvedVendorCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Vendors currently approved to join this location."},"createdAt":{"type":"string","description":"ISO-8601 UTC."},"images":{"type":"array","items":{"$ref":"#/components/schemas/ManagedLocationImage"}}},"required":["id","slug","name","address","city","countryCode","filterTags","url","imageUrl","latitude","longitude","accessMode","vendorDescription","upcomingEventCount","approvedVendorCount","createdAt","images"],"additionalProperties":false,"description":"Full detail of a location managed by the API key's creator."},"ManagedLocationImage":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"url":{"type":"string","format":"uri","description":"Public URL of the stored image."},"altText":{"anyOf":[{"type":"string"},{"type":"null"}]},"displayOrder":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Zero-based gallery position."},"isPrimary":{"type":"boolean","description":"True for the image shown as the location's main photo."},"createdAt":{"type":"string","description":"ISO-8601 UTC upload confirmation time."}},"required":["id","url","altText","displayOrder","isPrimary","createdAt"],"additionalProperties":false,"description":"One image in a location's gallery."},"ManagedLocationImagePresign":{"type":"object","properties":{"uploadUrl":{"type":"string","format":"uri","description":"Presigned R2 URL; PUT the file bytes here directly."},"publicUrl":{"type":"string","format":"uri","description":"Public URL the image will be served from once confirmed."},"key":{"type":"string","description":"Object key of the pending upload."},"expiresInSeconds":{"type":"number","const":300,"description":"Presigned URL lifetime; always 300 seconds (5 minutes)."}},"required":["uploadUrl","publicUrl","key","expiresInSeconds"],"additionalProperties":false,"description":"Presigned upload data for a location gallery image."},"DeletedLocationImageResult":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"deleted":{"type":"boolean","const":true}},"required":["id","deleted"],"additionalProperties":false,"description":"Result of a location image deletion."},"ReorderedLocationImagesResult":{"type":"object","properties":{"orderedIds":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"description":"Image ids in their new display order."}},"required":["orderedIds"],"additionalProperties":false,"description":"Result of a gallery reorder."},"Order":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"number":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"type":"string"},"total":{"type":"string","description":"Decimal string order total."},"paymentState":{"type":"string"},"paymentMethod":{"anyOf":[{"type":"string"},{"type":"null"}]},"note":{"anyOf":[{"type":"string"},{"type":"null"}]},"vendorNote":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},"completedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},{"type":"null"}]},"cancelledAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},{"type":"null"}]},"cancellationReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"cancelledBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"isGuestCheckout":{"type":"boolean"},"isNewCustomer":{"type":"boolean"},"customer":{"$ref":"#/components/schemas/OrderCustomer"},"event":{"type":"object","properties":{"startTime":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},{"type":"null"}]},"endTime":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},{"type":"null"}]},"locationName":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["startTime","endTime","locationName"],"additionalProperties":false},"items":{"type":"array","items":{"$ref":"#/components/schemas/OrderItem"}},"bill":{"type":"object","properties":{"invoiceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["invoiceId","status"],"additionalProperties":false},"paymentRequest":{"anyOf":[{"$ref":"#/components/schemas/PaymentRequest"},{"type":"null"}],"description":"The order's newest open payment request, else its newest in any status; null when none was issued."},"paymentRequests":{"type":"array","items":{"$ref":"#/components/schemas/PaymentRequest"},"description":"Every non-superseded payment request of the order, newest first; one per sales profile can be open."},"receiptGross":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Decimal string gross total of the order's issued Számlázz.hu receipt (summed over the receipts of a mixed basket). Null when none was issued or a receipt cannot be read. Can differ from `total`."},"teyaPayment":{"$ref":"#/components/schemas/OrderTeyaPayment"}},"required":["id","number","state","total","paymentState","paymentMethod","note","vendorNote","createdAt","completedAt","cancelledAt","cancellationReason","cancelledBy","isGuestCheckout","isNewCustomer","customer","event","items","bill","paymentRequest","paymentRequests","receiptGross","teyaPayment"],"additionalProperties":false,"description":"A vendor order in list form."},"OrderCustomer":{"type":"object","properties":{"publicId":{"anyOf":[{"type":"string"},{"type":"null"}]},"firstName":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastName":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["publicId","firstName","lastName","email","phone"],"additionalProperties":false,"description":"Buyer contact info; guests have a null publicId."},"OrderItem":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"productId":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"productName":{"type":"string"},"quantity":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Ordered piece/package count. For weight-sold products this is not kilograms."},"lineTotal":{"type":"string","description":"Decimal string rounded line total computed by the server. Use this for revenue, reporting, and reconciliation."},"unitPrice":{"type":"string","description":"Decimal string display unit price. For weight-sold products this is the kilogram price plus any selected per-piece option modifier."},"optionModifier":{"type":"string","description":"Decimal string per-piece option price delta included in unitPrice."},"weightGrams":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Measured total weight in grams for weight-sold items, otherwise null."},"selectedOptions":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},{"type":"null"}]},"isSoldByWeight":{"type":"boolean","description":"True when this item is priced by weight."},"averageWeight":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Decimal string average package weight in kilograms; used for estimated weight-sold totals when weightGrams is not set."},"unit":{"anyOf":[{"type":"string"},{"type":"null"}]},"basePrice":{"type":"string","description":"Decimal string list price."}},"required":["id","productId","productName","quantity","lineTotal","unitPrice","optionModifier","weightGrams","selectedOptions","isSoldByWeight","averageWeight","unit","basePrice"],"additionalProperties":false,"description":"A single order line item."},"PaymentRequest":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"orderId":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sequence":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"A per-order counter: 1 for the order's first request, then one higher per further request (another sales profile's or a re-issue)."},"documentNumber":{"type":"string","description":"`DB-<order number>-<sequence>`, as printed on the PDF."},"status":{"type":"string","enum":["issued","paid","cancelled","superseded"],"description":"`issued` is the open request; the others are closed."},"amount":{"type":"string","description":"Decimal string: this sales profile's share of the order total at issue (the whole total for a single-profile order)."},"currency":{"type":"string"},"dueDate":{"type":"string","description":"Europe/Budapest calendar day, `YYYY-MM-DD`."},"paymentReference":{"type":"string","description":"The transfer reference the buyer must quote: the order number."},"payeeName":{"type":"string"},"payeeBankAccount":{"type":"string","description":"The sales profile's bank account as printed, display-formatted."},"buyerName":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Null once the buyer's account was erased."},"buyerEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"issuedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},"paidAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},{"type":"null"}]},"paidVia":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"How it was settled: `manual`, `api`, `teya_terminal` or `teya_link`."},"cancelledAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},{"type":"null"}]},"cancelReason":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"`vendor`, `order_closed` or `reissued`."},"isOverdue":{"type":"boolean","description":"Still issued and the due date has passed."},"isStale":{"type":"boolean","description":"Still issued but the order total changed since issue."},"emailStatus":{"type":"string","description":"Buyer email delivery: `pending`, `sent` or `failed`."},"emailSentAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},{"type":"null"}]},"emailError":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Generic failure text, never a provider message."},"overdueNotifiedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},{"type":"null"}]},"profileId":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"The sales profile (the vendor's billing integration) the request collects for: its name is the payee. Null only on a request issued during a release-rollback window; treat it as the default profile."},"profileName":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The profile's current name; null when profileId is."}},"required":["id","orderId","sequence","documentNumber","status","amount","currency","dueDate","paymentReference","payeeName","payeeBankAccount","buyerName","buyerEmail","issuedAt","paidAt","paidVia","cancelledAt","cancelReason","isOverdue","isStale","emailStatus","emailSentAt","emailError","overdueNotifiedAt","profileId","profileName"],"additionalProperties":false,"description":"A payment request (bank-transfer pro forma) on an order. An order has one request per sales profile its lines belong to."},"OrderTeyaPayment":{"anyOf":[{"type":"object","properties":{"terminalId":{"type":"string","description":"Teya terminal id (8 characters, e.g. `SOCwINqJ`), as in the portal's \"Terminál azonosító\"."},"gatewayPaymentId":{"type":"string","description":"Teya transaction id, `tr_<uuid>`."},"capturedAmount":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Decimal string: the provider-confirmed amount, tip excluded. Null only on a legacy capture that never stored it."},"tipAmount":{"type":"string","description":"Decimal string tip added on the terminal; never part of the order total."},"finalizedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$","description":"When the capture was finalized on our side."},"portalPaymentId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"`gatewayPaymentId` without the `tr_` prefix: the Teya portal export's \"Fizetési azonosító\". Null when the gateway id is not `tr_<uuid>`."},"authCode":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Issuer approval code (6 characters, usually digits), the portal's \"Jóváhagyási kód\". Null when the terminal reported none."}},"required":["terminalId","gatewayPaymentId","capturedAmount","tipAmount","finalizedAt","portalPaymentId","authCode"],"additionalProperties":false},{"type":"null"}],"description":"The order's successful Teya card-terminal (POSLink) capture; null when there is none. With more than one, the latest finalizedAt."},"OrderDetail":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"eventId":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"number":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"type":"string"},"total":{"type":"string"},"paymentState":{"type":"string"},"paymentMethod":{"anyOf":[{"type":"string"},{"type":"null"}]},"note":{"anyOf":[{"type":"string"},{"type":"null"}]},"vendorNote":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},"completedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},{"type":"null"}]},"cancelledAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},{"type":"null"}]},"cancellationReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"cancelledBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"isGuestCheckout":{"type":"boolean"},"customer":{"$ref":"#/components/schemas/OrderCustomer"},"event":{"type":"object","properties":{"startTime":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},{"type":"null"}]},"endTime":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},{"type":"null"}]},"locationName":{"anyOf":[{"type":"string"},{"type":"null"}]},"locationAddress":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["startTime","endTime","locationName","locationAddress"],"additionalProperties":false},"delivery":{"$ref":"#/components/schemas/OrderDelivery"},"items":{"type":"array","items":{"$ref":"#/components/schemas/OrderItem"}},"bill":{"type":"object","properties":{"invoiceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"errorMessage":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["invoiceId","status","errorMessage"],"additionalProperties":false},"paymentRequest":{"anyOf":[{"$ref":"#/components/schemas/PaymentRequest"},{"type":"null"}],"description":"The order's newest open payment request, else its newest in any status; null when none was issued."},"paymentRequests":{"type":"array","items":{"$ref":"#/components/schemas/PaymentRequest"},"description":"Every non-superseded payment request of the order, newest first; one per sales profile can be open."},"receiptGross":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Decimal string gross total of the order's issued Számlázz.hu receipt (summed over the receipts of a mixed basket). Null when none was issued or a receipt cannot be read. Can differ from `total`."},"teyaPayment":{"$ref":"#/components/schemas/OrderTeyaPayment"}},"required":["id","eventId","number","state","total","paymentState","paymentMethod","note","vendorNote","createdAt","updatedAt","completedAt","cancelledAt","cancellationReason","cancelledBy","isGuestCheckout","customer","event","delivery","items","bill","paymentRequest","paymentRequests","receiptGross","teyaPayment"],"additionalProperties":false,"description":"Full detail of a single vendor order."},"OrderDelivery":{"anyOf":[{"type":"object","properties":{"recipientName":{"type":"string"},"phone":{"type":"string"},"postalCode":{"type":"string"},"city":{"type":"string"},"streetAddress":{"type":"string"},"addressNote":{"anyOf":[{"type":"string"},{"type":"null"}]},"deliveryStatus":{"type":"string","enum":["pending","out_for_delivery","delivered"]},"trackingUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"deliveryFee":{"type":"string","description":"Decimal string, included in the order total."}},"required":["recipientName","phone","postalCode","city","streetAddress","addressNote","deliveryStatus","trackingUrl","deliveryFee"],"additionalProperties":false},{"type":"null"}],"description":"Home-delivery address and courier progress."},"EventOrder":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"number":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"type":"string"},"total":{"type":"string"},"paymentState":{"type":"string"},"paymentMethod":{"anyOf":[{"type":"string"},{"type":"null"}]},"note":{"anyOf":[{"type":"string"},{"type":"null"}]},"vendorNote":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},"isNewCustomer":{"type":"boolean"},"customer":{"$ref":"#/components/schemas/OrderCustomer"},"items":{"type":"array","items":{"$ref":"#/components/schemas/EventOrderItem"}}},"required":["id","number","state","total","paymentState","paymentMethod","note","vendorNote","createdAt","isNewCustomer","customer","items"],"additionalProperties":false,"description":"A vendor order in the by-event view."},"EventOrderItem":{"type":"object","properties":{"productName":{"type":"string"},"quantity":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Ordered piece/package count. For weight-sold products this is not kilograms."},"lineTotal":{"type":"string","description":"Decimal string rounded line total computed by the server. Use this for revenue, reporting, and reconciliation."},"unitPrice":{"type":"string","description":"Decimal string display unit price. For weight-sold products this is the kilogram price plus any selected per-piece option modifier."},"optionModifier":{"type":"string","description":"Decimal string per-piece option price delta included in unitPrice."},"weightGrams":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Measured total weight in grams for weight-sold items, otherwise null."},"selectedOptions":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},{"type":"null"}]},"isSoldByWeight":{"type":"boolean","description":"True when this item is priced by weight."},"averageWeight":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Decimal string average package weight in kilograms; used for estimated weight-sold totals when weightGrams is not set."},"unit":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["productName","quantity","lineTotal","unitPrice","optionModifier","weightGrams","selectedOptions","isSoldByWeight","averageWeight","unit"],"additionalProperties":false,"description":"Order line item in the by-event view."},"PaymentRequestEligibility":{"type":"object","properties":{"canIssue":{"type":"boolean"},"reasons":{"type":"array","items":{"$ref":"#/components/schemas/PaymentRequestReason"},"description":"Why a request cannot be issued now; empty when canIssue."},"defaults":{"type":"object","properties":{"buyerName":{"anyOf":[{"type":"string"},{"type":"null"}]},"buyerEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"dueDate":{"type":"string","description":"Budapest today + 7 days, `YYYY-MM-DD`."}},"required":["buyerName","buyerEmail","dueDate"],"additionalProperties":false},"baseline":{"type":"string","description":"Send back as `expectedBaseline` when issuing."},"groups":{"type":"array","items":{"$ref":"#/components/schemas/PaymentRequestGroup"},"description":"The order's split per sales profile, by profileId."}},"required":["canIssue","reasons","defaults","baseline","groups"],"additionalProperties":false,"description":"Whether and with what defaults a request can be issued."},"PaymentRequestReason":{"type":"string","enum":["order_not_found","invalid_order_state","bank_account_missing","weight_required","hidden_product","order_refunded","baseline_changed","open_request_exists","request_not_found","request_not_open","request_stale","buyer_email_missing","invalid_due_date","send_limit_reached"],"description":"Machine-readable payment-request outcome; also the `details.reason` of an error."},"PaymentRequestGroup":{"type":"object","properties":{"profileId":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The sales profile (billing integration id)."},"profileName":{"type":"string","description":"The profile's name: the payee on its request."},"amount":{"type":"string","description":"Decimal string: what this group's request asks for."},"hasBankAccount":{"type":"boolean","description":"The profile has a bank account; a group to be requested without one blocks issuing (bank_account_missing)."},"covered":{"type":"boolean","description":"An open or a paid request already covers the group; issuing skips it."}},"required":["profileId","profileName","amount","hasBankAccount","covered"],"additionalProperties":false,"description":"One sales-profile group of an order; the groups' amounts add up to the order total. Ordered by profileId."},"ProductListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProductListItem"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"],"additionalProperties":false},"ProductListItem":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"example":123},"name":{"type":"string"},"slug":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"price":{"type":"string","description":"Decimal value as a string.","example":"1200.00"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}]},"averageWeight":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Decimal value as a string."},"isSoldByWeight":{"type":"boolean"},"vatRate":{"type":"string","example":"27"},"preparationDays":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"status":{"type":"string","example":"active"},"isHidden":{"type":"boolean"},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"tags":{"type":"array","items":{"type":"string"},"description":"Backward-compatible tag display names. Derived from structured tag assignments when available; otherwise contains legacy flat tag names."},"tagIds":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"},"description":"Structured tag IDs assigned to the product. Use these IDs in POST or PATCH tagIds; empty when tags contains only legacy flat tag names."},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO-8601 UTC timestamp.","example":"2026-01-01T00:00:00.000Z"},"options":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"choices":{"type":"array","items":{"type":"string"}},"price_modifier":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"number"}},"preparation_days":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["choices"],"additionalProperties":false}},{"type":"null"}],"description":"Full option-group definition (same shape as the detail) — build a product/variant mapping from one paginated list call."},"supply":{"type":"object","properties":{"activeCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of active supplies."},"totalAvailable":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalReserved":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["activeCount","totalAvailable","totalReserved"],"additionalProperties":false}},"required":["id","name","slug","description","price","unit","averageWeight","isSoldByWeight","vatRate","preparationDays","status","isHidden","imageUrl","tags","tagIds","createdAt","options","supply"],"additionalProperties":false,"description":"A vendor product with its aggregated active-supply summary."},"ProductResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Product"}},"required":["data"],"additionalProperties":false},"Product":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"example":123},"name":{"type":"string"},"slug":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"price":{"type":"string","description":"Decimal value as a string.","example":"1200.00"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}]},"averageWeight":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Decimal value as a string."},"isSoldByWeight":{"type":"boolean"},"vatRate":{"type":"string","example":"27"},"preparationDays":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"status":{"type":"string","example":"active"},"isHidden":{"type":"boolean"},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"tags":{"type":"array","items":{"type":"string"},"description":"Backward-compatible tag display names. Derived from structured tag assignments when available; otherwise contains legacy flat tag names."},"tagIds":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"},"description":"Structured tag IDs assigned to the product. Use these IDs in POST or PATCH tagIds; empty when tags contains only legacy flat tag names."},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO-8601 UTC timestamp.","example":"2026-01-01T00:00:00.000Z"},"options":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"choices":{"type":"array","items":{"type":"string"}},"price_modifier":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"number"}},"preparation_days":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["choices"],"additionalProperties":false}},{"type":"null"}]}},"required":["id","name","slug","description","price","unit","averageWeight","isSoldByWeight","vatRate","preparationDays","status","isHidden","imageUrl","tags","tagIds","createdAt","options"],"additionalProperties":false,"description":"A vendor product."},"ReviewListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Review"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"],"additionalProperties":false},"Review":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"orderId":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"kind":{"type":"string","enum":["vendor","product"]},"product":{"anyOf":[{"$ref":"#/components/schemas/ReviewProduct"},{"type":"null"}]},"recommends":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"rating":{"anyOf":[{"type":"integer","minimum":1,"maximum":5},{"type":"null"}]},"comment":{"anyOf":[{"type":"string"},{"type":"null"}]},"tags":{"type":"array","items":{"$ref":"#/components/schemas/ReviewTag"}},"vendorReply":{"anyOf":[{"type":"string"},{"type":"null"}]},"vendorReplyAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"}},"required":["id","orderId","kind","product","recommends","rating","comment","tags","vendorReply","vendorReplyAt","createdAt","updatedAt"],"additionalProperties":false,"description":"A visible vendor-owned review. Reviewer identity and contact fields are deliberately excluded."},"ReviewProduct":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"description":"The reviewed product."},"ReviewTag":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"name":{"type":"string"},"emoji":{"type":"string"}},"required":["id","name","emoji"],"additionalProperties":false,"description":"A structured tag selected by the reviewer."},"ReviewResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Review"}},"required":["data"],"additionalProperties":false},"SupplyListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SupplyListItem"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"],"additionalProperties":false},"SupplyListItem":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"example":456},"productId":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"example":123},"productName":{"type":"string"},"quantity":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total units in this supply window."},"reserved":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Units already reserved by orders."},"available":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Buyable remainder: max(0, quantity - reserved)."},"availableFrom":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO-8601 UTC start of the supply window.","example":"2026-06-01T08:00:00.000Z"},"availableUntil":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO-8601 UTC end of the supply window.","example":"2026-06-08T18:00:00.000Z"},"state":{"type":"string","description":"Supply state: `active`, `cancelled`, or `closed` (residual row left by a production close — serves its existing orders, takes no new ones).","example":"active"},"selectedOptions":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},{"type":"null"}],"description":"Exact option combination this row serves (produced form row); `null` for a product-level base pool shared by every combination.","example":{"Csomag:":"Darabolt, vákumcsomagolt"}},"producedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Set when the stock physically exists (form rows always; base rows after a production close). Produced stock is exempt from preparation-time gating.","example":"2026-08-05T09:00:00.000Z"},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO-8601 UTC timestamp.","example":"2026-01-01T00:00:00.000Z"}},"required":["id","productId","productName","quantity","reserved","available","availableFrom","availableUntil","state","selectedOptions","producedAt","createdAt"],"additionalProperties":false,"description":"A vendor supply window."},"SupplyResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Supply"}},"required":["data"],"additionalProperties":false},"Supply":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"example":456},"productId":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"example":123},"productName":{"type":"string"},"quantity":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total units in this supply window."},"reserved":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Units already reserved by orders."},"available":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Buyable remainder: max(0, quantity - reserved)."},"availableFrom":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO-8601 UTC start of the supply window.","example":"2026-06-01T08:00:00.000Z"},"availableUntil":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO-8601 UTC end of the supply window.","example":"2026-06-08T18:00:00.000Z"},"state":{"type":"string","description":"Supply state: `active`, `cancelled`, or `closed` (residual row left by a production close — serves its existing orders, takes no new ones).","example":"active"},"selectedOptions":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},{"type":"null"}],"description":"Exact option combination this row serves (produced form row); `null` for a product-level base pool shared by every combination.","example":{"Csomag:":"Darabolt, vákumcsomagolt"}},"producedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Set when the stock physically exists (form rows always; base rows after a production close). Produced stock is exempt from preparation-time gating.","example":"2026-08-05T09:00:00.000Z"},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO-8601 UTC timestamp.","example":"2026-01-01T00:00:00.000Z"}},"required":["id","productId","productName","quantity","reserved","available","availableFrom","availableUntil","state","selectedOptions","producedAt","createdAt"],"additionalProperties":false,"description":"A vendor supply window."},"ProductionCloseResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProductionCloseResult"}},"required":["data"],"additionalProperties":false},"ProductionCloseResult":{"type":"object","properties":{"baseSupplyId":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"The transitioned base supply, when one was given."},"created":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"selectedOptions":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"quantity":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"reserved":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Reservations moved onto this form row."}},"required":["id","selectedOptions","quantity","reserved"],"additionalProperties":false},"description":"The produced form rows created by this call."},"shortfalls":{"type":"array","items":{"type":"object","properties":{"supplyId":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"selectedOptions":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},{"type":"null"}]},"quantity":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"reserved":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["supplyId","selectedOptions","quantity","reserved"],"additionalProperties":false},"description":"Rows left with reserved > quantity: fewer units were produced than already promised (vendor-oversell state, allowed but reported)."},"orphans":{"type":"array","items":{"type":"object","properties":{"orderItemId":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"orderId":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"selectedOptions":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},{"type":"null"}]},"quantity":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["orderItemId","orderId","selectedOptions","quantity"],"additionalProperties":false},"description":"Reservations whose form was not produced — left on the residual (state='closed') row. Resolve by re-running the close with the missing variants once produced."},"residualSupplyId":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"The closed residual row still holding orphan reservations, when any remain."}},"required":["baseSupplyId","created","shortfalls","orphans","residualSupplyId"],"additionalProperties":false},"SupplyForecastResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SupplyForecast"}},"required":["data"],"additionalProperties":false},"SupplyForecast":{"type":"object","properties":{"consumptionTrends":{"type":"array","items":{"$ref":"#/components/schemas/SupplyForecastConsumptionTrend"}},"eventRestockSuggestions":{"type":"array","items":{"$ref":"#/components/schemas/SupplyForecastRestockSuggestion"},"description":"Sorted by deficit descending (most urgent first)."},"seasonalPatterns":{"type":"array","items":{"$ref":"#/components/schemas/SupplyForecastSeasonalPattern"},"description":"Only products with 3+ distinct months of sales history."}},"required":["consumptionTrends","eventRestockSuggestions","seasonalPatterns"],"additionalProperties":false},"SupplyForecastConsumptionTrend":{"type":"object","properties":{"productId":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"example":77},"productName":{"type":"string","example":"Sourdough loaf"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"example":"piece"},"weeklyTrend":{"type":"array","items":{"$ref":"#/components/schemas/SupplyForecastTrendPoint"},"description":"Units sold per week over the trailing 12 weeks."},"monthlyTrend":{"type":"array","items":{"$ref":"#/components/schemas/SupplyForecastTrendPoint"},"description":"Units sold per month over the trailing 6 months."}},"required":["productId","productName","unit","weeklyTrend","monthlyTrend"],"additionalProperties":false},"SupplyForecastTrendPoint":{"type":"object","properties":{"periodLabel":{"type":"string","description":"ISO week (\"2026-W30\") for weekly trends, calendar month (\"2026-07\") for monthly trends."},"quantity":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Units sold (completed orders) in the period.","example":18}},"required":["periodLabel","quantity"],"additionalProperties":false},"SupplyForecastRestockSuggestion":{"type":"object","properties":{"productId":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"example":77},"productName":{"type":"string","example":"Sourdough loaf"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"example":"piece"},"upcomingEventCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Upcoming non-hidden events the vendor has joined.","example":3},"avgQuantityPerEvent":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Rounded average units sold per past event (completed orders).","example":14},"suggestedRestock":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"avgQuantityPerEvent × upcomingEventCount.","example":42},"currentNetAvailable":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Units available in currently active supply windows.","example":10},"deficit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"max(0, suggestedRestock − currentNetAvailable).","example":32}},"required":["productId","productName","unit","upcomingEventCount","avgQuantityPerEvent","suggestedRestock","currentNetAvailable","deficit"],"additionalProperties":false},"SupplyForecastSeasonalPattern":{"type":"object","properties":{"productId":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"example":77},"productName":{"type":"string","example":"Sourdough loaf"},"monthlyAvg":{"type":"array","items":{"type":"object","properties":{"month":{"type":"integer","minimum":1,"maximum":12,"example":7},"avgQuantity":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Average units sold in that calendar month across years.","example":64}},"required":["month","avgQuantity"],"additionalProperties":false},"description":"One entry per calendar month with sales history."},"peakMonth":{"type":"integer","minimum":1,"maximum":12,"description":"Calendar month with the highest average quantity.","example":7},"troughMonth":{"type":"integer","minimum":1,"maximum":12,"description":"Calendar month with the lowest average quantity.","example":2}},"required":["productId","productName","monthlyAvg","peakMonth","troughMonth"],"additionalProperties":false},"SupplyDeleteResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"SupportAccountLookupResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SupportAccountLookup"}},"required":["data"],"additionalProperties":false},"SupportAccountLookup":{"type":"object","properties":{"email":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$","example":"producer@example.com"},"exists":{"type":"boolean","description":"A live (not deleted) account uses this address."},"account":{"anyOf":[{"$ref":"#/components/schemas/SupportAccount"},{"type":"null"}]}},"required":["email","exists","account"],"additionalProperties":false},"SupportAccount":{"type":"object","properties":{"userId":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"example":512},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},"emailConfirmed":{"type":"boolean","description":"The address was confirmed (or the account activated)."},"hasPassword":{"type":"boolean","description":"The account can sign in with a password."},"oauthProviders":{"type":"array","items":{"type":"string"},"description":"Linked sign-in providers.","example":["google"]},"guestOnly":{"type":"boolean","description":"No password, unconfirmed, no linked provider: a guest-checkout account. `/register` with this address emails an activation link instead of creating an account."},"banned":{"type":"boolean"},"locked":{"type":"boolean","description":"Temporarily locked after failed password attempts."},"vendorRole":{"type":"string","description":"`owner` or `helper` (market-day helper).","example":"owner"},"vendor":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"name":{"type":"string"},"state":{"type":"string","example":"active"},"deleted":{"type":"boolean"}},"required":["id","name","state","deleted"],"additionalProperties":false},{"type":"null"}],"description":"The vendor this account belongs to, or null for a buyer-only account."},"organizedLocations":{"type":"array","items":{"type":"object","properties":{"locationId":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"name":{"type":"string"},"deleted":{"type":"boolean"}},"required":["locationId","name","deleted"],"additionalProperties":false},"description":"Locations listing this account as organizer (ADR-037), in added order."}},"required":["userId","createdAt","emailConfirmed","hasPassword","oauthProviders","guestOnly","banned","locked","vendorRole","vendor","organizedLocations"],"additionalProperties":false},"SupportCommunityMarketStateResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SupportCommunityMarketState"}},"required":["data"],"additionalProperties":false},"SupportCommunityMarketState":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"example":88},"slug":{"type":"string","example":"godollo-piac"},"name":{"type":"string"},"status":{"type":"string","enum":["active","threshold_reached","activated","closed"]},"phase":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"1 community, 2 organizing, 3 first market.","example":2},"supporterCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"vendorInterestCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"thresholdReachedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},{"type":"null"}]},"organizerUserId":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"The suggestion's organizer, or null when none is set."},"organizerListedOnLocation":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Whether that organizer is also on the linked location's organizer list. Null when no organizer is set or no location is linked."},"locationId":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"locationFollowerCount":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"firstEventId":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"firstMarketAnnouncedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},{"type":"null"}]}},"required":["id","slug","name","status","phase","supporterCount","vendorInterestCount","thresholdReachedAt","organizerUserId","organizerListedOnLocation","locationId","locationFollowerCount","firstEventId","firstMarketAnnouncedAt"],"additionalProperties":false},"SupportActivateCommunityMarketResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SupportActivateCommunityMarketResult"}},"required":["data"],"additionalProperties":false},"SupportActivateCommunityMarketResult":{"type":"object","properties":{"suggestionId":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"example":88},"slug":{"type":"string","example":"godollo-piac"},"status":{"type":"string","const":"activated"},"locationId":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"example":71},"locationSlug":{"type":"string","example":"godollo"},"locationReused":{"type":"boolean","description":"True when the market's live linked location was reused; false when a new location was created."},"followersMigrated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Supporters newly added as followers of the location."},"emailsScheduled":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Activation emails scheduled after commit (supporters who have not opted out); 0 with `notifySupporters: false`."}},"required":["suggestionId","slug","status","locationId","locationSlug","locationReused","followersMigrated","emailsScheduled"],"additionalProperties":false},"SupportLocationResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SupportLocation"}},"required":["data"],"additionalProperties":false},"SupportLocation":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"example":71},"name":{"type":"string"},"slug":{"type":"string"},"deleted":{"type":"boolean"},"ownerVendorId":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"accessMode":{"type":"string","example":"open"},"fulfillmentMode":{"type":"string","example":"pickup"},"followerCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"organizers":{"type":"array","items":{"$ref":"#/components/schemas/SupportLocationOrganizer"}},"upcomingEvents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"startTime":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$","example":"2026-10-30T07:00:00.000Z"},"endTime":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$","example":"2026-10-30T11:00:00.000Z"},"startTimeLocal":{"type":"string","description":"Europe/Budapest wall-clock with that moment's UTC offset.","example":"2026-10-30T08:00:00+01:00"},"endTimeLocal":{"type":"string","example":"2026-10-30T12:00:00+01:00"},"hidden":{"type":"boolean"},"vendors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}}},"required":["id","startTime","endTime","startTimeLocal","endTimeLocal","hidden","vendors"],"additionalProperties":false},"description":"Market days that have not ended yet, earliest first (hidden ones included; at most 50)."},"communityMarkets":{"type":"array","items":{"$ref":"#/components/schemas/SupportCommunityMarketState"}}},"required":["id","name","slug","deleted","ownerVendorId","accessMode","fulfillmentMode","followerCount","organizers","upcomingEvents","communityMarkets"],"additionalProperties":false},"SupportLocationOrganizer":{"type":"object","properties":{"userId":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"live":{"type":"boolean","description":"Not deleted, banned or a market helper — counts toward the last-organizer rule."},"addedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"}},"required":["userId","name","live","addedAt"],"additionalProperties":false},"SupportAddOrganizerResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SupportAddOrganizerResult"}},"required":["data"],"additionalProperties":false},"SupportAddOrganizerResult":{"type":"object","properties":{"locationId":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"added":{"type":"boolean","description":"Always false: an invited account is listed only once it accepts the emailed invitation."},"invited":{"type":"boolean","description":"True when a pending invitation was created or renewed; false when the account was already listed (nothing written)."},"organizers":{"type":"array","items":{"$ref":"#/components/schemas/SupportLocationOrganizer"}}},"required":["locationId","added","invited","organizers"],"additionalProperties":false},"SupportCreateMarketDaysResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SupportCreateMarketDaysResult"}},"required":["data"],"additionalProperties":false},"SupportCreateMarketDaysResult":{"type":"object","properties":{"locationId":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"startTime":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$","example":"2026-10-30T07:00:00.000Z"},"endTime":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$","example":"2026-10-30T11:00:00.000Z"},"startTimeLocal":{"type":"string","description":"Europe/Budapest wall-clock with that moment's UTC offset.","example":"2026-10-30T08:00:00+01:00"},"endTimeLocal":{"type":"string","example":"2026-10-30T12:00:00+01:00"},"hidden":{"type":"boolean"},"vendorIds":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}}},"required":["id","startTime","endTime","startTimeLocal","endTimeLocal","hidden","vendorIds"],"additionalProperties":false}}},"required":["locationId","events"],"additionalProperties":false},"TagListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Tag"}}},"required":["data"],"additionalProperties":false},"Tag":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$","description":"Tag id used in product `tagIds`."},"name":{"type":"string","example":"🥚 Tojás"},"slug":{"type":"string","example":"tojas"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","slug","description"],"additionalProperties":false,"description":"A product taxonomy tag."},"WebhookListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}}},"required":["data"],"additionalProperties":false},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"example":12},"url":{"type":"string","example":"https://pos.example.com/webhooks/villampiac"},"enabledEvents":{"type":"array","items":{"type":"string","enum":["order.created","order.state_changed","order.updated","supply.low","event.reminder","review.submitted"]},"description":"Subscribed event types."},"status":{"type":"string","description":"`enabled` | `disabled`.","example":"enabled"},"disabledReason":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"`delivery_failures` | `manual` | null.","example":null},"consecutiveFailures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Consecutive dead-lettered deliveries; auto-disables at 20."},"secretMasked":{"type":"string","description":"Masked display value, e.g. `whsec_…2f9c`. Never the real secret.","example":"whsec_…2f9c"},"lastDeliveryAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO-8601 timestamp of the last successful delivery, or null."},"createdAt":{"type":"string","description":"ISO-8601 UTC timestamp.","example":"2026-06-08T09:30:00.000Z"}},"required":["id","url","enabledEvents","status","disabledReason","consecutiveFailures","secretMasked","lastDeliveryAt","createdAt"],"additionalProperties":false,"description":"A masked outbound webhook endpoint."},"WebhookCreateResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"example":12},"url":{"type":"string","example":"https://pos.example.com/webhooks/villampiac"},"enabledEvents":{"type":"array","items":{"type":"string","enum":["order.created","order.state_changed","order.updated","supply.low","event.reminder","review.submitted"]},"description":"Subscribed event types."},"status":{"type":"string","description":"`enabled` | `disabled`.","example":"enabled"},"disabledReason":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"`delivery_failures` | `manual` | null.","example":null},"consecutiveFailures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Consecutive dead-lettered deliveries; auto-disables at 20."},"secretMasked":{"type":"string","description":"Masked display value, e.g. `whsec_…2f9c`. Never the real secret.","example":"whsec_…2f9c"},"lastDeliveryAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO-8601 timestamp of the last successful delivery, or null."},"createdAt":{"type":"string","description":"ISO-8601 UTC timestamp.","example":"2026-06-08T09:30:00.000Z"},"secret":{"type":"string","description":"The raw `whsec_…` signing secret. Returned exactly once, in this response; it is never stored in plaintext and can never be retrieved again.","example":"whsec_9f2ac1e4b7d04f8a9c3e5d6b7a8f0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8"}},"required":["id","url","enabledEvents","status","disabledReason","consecutiveFailures","secretMasked","lastDeliveryAt","createdAt","secret"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"WebhookDeleteResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}},"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Send the key as `Authorization: Bearer vp_live_…` (the `x-api-key` header is also accepted)."}}}}