{"openapi":"3.1.0","info":{"title":"Johku Partner API","version":"1.0.1","description":"Curated, versioned access to Johku shops for verified partners. Every shop must connect your integration before you can use its data; Johku Atlas (/v1/atlas, with the atlas:read scope Johku grants) searches across all shops that haven't opted out.\n\nMoney is in minor units with the shop currency. Times are ISO 8601 with an offset; shops run on Europe/Helsinki. Errors are RFC 9457 problem+json with a stable `code`.\n\nThe booking flow step by step, with what each kind of product needs in its booking line: [the guide](/guide.md), section 7."},"servers":[{"url":"https://api.johku.com"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"A partner API key: `Authorization: Bearer jk_live_…` (secret, server side only) or `jk_pub_live_…` (publishable, browser, origin-restricted)."}},"schemas":{"Me":{"type":"object","properties":{"partner":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["pending","pilot","verified","suspended"]}},"required":["id","name","status"],"description":"The partner the key belongs to. status: pending (test keys only, against the sandbox shop), pilot (live keys for a limited number of shops while Johku reviews the first integration), verified, or suspended"},"integration":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"scopes":{"type":"array","items":{"$ref":"#/components/schemas/Scope"}}},"required":["id","name","scopes"],"description":"The integration the key belongs to, with its scopes. Each shop grants its own share of them: see GET /v1/connections"},"key":{"type":"object","properties":{"prefix":{"type":"string","example":"jk_live_a1b2c3"},"kind":{"type":"string","enum":["secret","publishable"]},"env":{"type":"string","enum":["test","live"]},"expires_at":{"type":["string","null"],"example":"2027-01-01T00:00:00.000Z"}},"required":["prefix","kind","env","expires_at"],"description":"The key making this request: its visible prefix, its kind (secret for servers, publishable for browsers), test or live, and when it expires (null: never)"},"limits":{"type":"object","properties":{"per_minute":{"type":"integer"},"per_day":{"type":"integer"},"concurrency":{"type":"integer"}},"required":["per_minute","per_day","concurrency"],"description":"per_minute and per_day: the key's quotas, in cost units (a product read costs 1, availability 3, a report 10); concurrency: how many of the partner's requests may run at once"}},"required":["partner","integration","key","limits"]},"Scope":{"type":"string","enum":["catalog:read","availability:read","booking:write","booking:confirm","orders:read","customers:read","reports:read","atlas:read"],"description":"atlas:read is granted to the integration by Johku; the others are granted by each shop"},"Problem":{"type":"object","properties":{"type":{"type":"string","description":"https://api.johku.com/problems/ and the code in lower case with hyphens"},"title":{"type":"string","description":"A short summary in English; may be reworded, so branch on `code`"},"status":{"type":"integer","description":"The HTTP status code of the response"},"code":{"type":"string","description":"Stable and machine-readable; each response lists its codes in its examples"},"detail":{"type":"string","description":"What went wrong in this case and, when it helps, what to do about it"},"instance":{"type":"string","example":"/v1/shops/johkula/products","description":"The path of the request that failed"},"errors":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"line":{"type":"integer"},"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"description":"Each problem found: `path` names the request field, `line` the index of the booking line it concerns"}},"required":["type","title","status","code"]},"Shop":{"type":"object","properties":{"id":{"type":"string","example":"johkula","description":"The shop id in /v1/shops/{shop}/… paths: the subdomain of its storefront"},"name":{"type":"string","example":"Demo Adventures Oy","description":"The shop's name"},"currency":{"type":"string","minLength":3,"maxLength":3,"example":"EUR","description":"ISO 4217; the shop's prices are all in it"},"locale":{"type":"string","example":"fi-FI","description":"The language of this response"},"default_locale":{"type":"string","example":"fi-FI","description":"BCP 47 language tag"},"locales":{"type":"array","items":{"type":"string","example":"fi-FI","description":"BCP 47 language tag"},"description":"Languages the shop offers; send one in Accept-Language"},"timezone":{"type":"string","example":"Europe/Helsinki","description":"All shops currently use Europe/Helsinki"},"storefront_url":{"type":"string","format":"uri","example":"https://johkula.johku.com","description":"The shop's web shop on Johku"},"logo_url":{"type":["string","null"],"format":"uri","description":"The shop's logo; null when it has none"},"business_id":{"type":["string","null"],"example":"1234567-8","description":"The Finnish business ID (Y-tunnus)"},"website":{"type":["string","null"],"description":"The shop's own website, apart from its Johku storefront"},"contact":{"type":"object","properties":{"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"address":{"type":"object","properties":{"street":{"type":["string","null"]},"postal_code":{"type":["string","null"]},"city":{"type":["string","null"]},"country":{"type":["string","null"],"example":"FI","description":"ISO 3166-1 alpha-2"}},"required":["street","postal_code","city","country"]}},"required":["email","phone","address"],"description":"Email and phone are null when the shop hides its contact details"}},"required":["id","name","currency","locale","default_locale","locales","timezone","storefront_url","logo_url","business_id","website","contact"]},"CategoryList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Category"},"description":"The categories, highest `priority` first, as the storefront orders them"}},"required":["data"]},"Category":{"type":"object","properties":{"id":{"type":"integer","example":9,"description":"For GET …/categories/{id} and GET …/products?category={id}"},"name":{"type":"string","description":"In the language chosen with Accept-Language, falling back to the shop default","example":"Accommodation"},"description":{"type":["string","null"],"description":"HTML"},"slug":{"type":["string","null"],"example":"accommodation","description":"The category's name in storefront URLs"},"priority":{"type":"integer","description":"Higher first, as the storefront orders them"},"image":{"anyOf":[{"$ref":"#/components/schemas/Image"},{"type":"null"}],"description":"The category's image; null when it has none"},"storefront_url":{"type":["string","null"],"format":"uri","description":"The category on the shop's storefront"}},"required":["id","name","description","slug","priority","image","storefront_url"]},"Image":{"type":"object","properties":{"url":{"type":"string","format":"uri","example":"https://cdn.johku.com/johkula/largefiles/193-sauna.jpg","description":"The full-size image"},"thumbnail_url":{"type":"string","format":"uri","example":"https://cdn.johku.com/johkula/files/193-sauna.jpg","description":"A smaller version for lists"},"title":{"type":["string","null"],"description":"The title the shop gave the image, if any"},"alt":{"type":["string","null"],"description":"Alternative text for screen readers, if the shop wrote one"}},"required":["url","thumbnail_url","title","alt"]},"ProductPage":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProductSummary"},"description":"The items on this page"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page"}},"required":["data","next_cursor"]},"ProductSummary":{"type":"object","properties":{"id":{"type":"integer","example":259,"description":"For GET …/products/{id} and `product_id` in booking lines"},"name":{"type":"string","description":"In the language chosen with Accept-Language, falling back to the shop default","example":"Sauna evening"},"kind":{"$ref":"#/components/schemas/ProductKind"},"from_price":{"anyOf":[{"$ref":"#/components/schemas/Money"},{"type":"null"}],"description":"The lowest price shown on the storefront; null when the shop hides prices"},"image":{"anyOf":[{"$ref":"#/components/schemas/Image"},{"type":"null"}],"description":"The main image; null when there is none"},"booking_url":{"type":"string","format":"uri","example":"https://johkula.johku.com/fi_FI/sauna-evening","description":"The product on the shop's own storefront, where any product can be booked"}},"required":["id","name","kind","from_price","image","booking_url"]},"ProductKind":{"type":"string","enum":["product","reservable","event","transport","giftcard"],"description":"product: bought as is; reservable: booked for a date or time; event: shows; transport: departures; giftcard: value cards"},"Money":{"type":"object","properties":{"amount":{"type":"integer","example":2450,"description":"Minor units, e.g. cents"},"currency":{"type":"string","minLength":3,"maxLength":3,"example":"EUR","description":"ISO 4217 currency code"}},"required":["amount","currency"],"description":"An amount in minor units with its currency. Prices and totals include VAT; a report's `net` amounts don't."},"Product":{"type":"object","properties":{"id":{"type":"integer","example":259,"description":"For `product_id` in booking lines"},"name":{"type":"string","description":"In the language chosen with Accept-Language, falling back to the shop default"},"description":{"type":["string","null"],"description":"HTML"},"kind":{"$ref":"#/components/schemas/ProductKind"},"from_price":{"anyOf":[{"$ref":"#/components/schemas/Money"},{"type":"null"}],"description":"The lowest price shown on the storefront; null when the shop hides prices"},"images":{"type":"array","items":{"$ref":"#/components/schemas/Image"},"description":"The main image first (unless the product hides it), then the gallery"},"categories":{"type":"array","items":{"$ref":"#/components/schemas/ProductCategory"},"description":"The storefront categories the product is listed in, in the order GET …/categories lists them. Only categories that list shows: categories the shop keeps for its POS or hides from the storefront are left out. Empty when the product is in none.","example":[{"id":9,"name":"Accommodation"},{"id":14,"name":"Lakeside cabins"}]},"price_tiers":{"type":"array","items":{"$ref":"#/components/schemas/PriceTier"},"description":"Participant types such as adults and children, used as `participants` keys in booking lines"},"allow_multiday":{"type":"boolean","description":"One booking may cover several days: a daily booking then takes `nights` or `end_date`; otherwise its length is fixed"},"booking_url":{"type":"string","format":"uri","description":"The product on the shop's own storefront, where any product can be booked"},"bookable_via_api":{"type":"boolean","description":"False when the product can only be booked through `booking_url`"},"booking_mode":{"anyOf":[{"$ref":"#/components/schemas/BookingMode"},{"type":"null"}],"description":"The line shape booking-options expects; null when the product can't be booked"}},"required":["id","name","description","kind","from_price","images","categories","price_tiers","allow_multiday","booking_url","bookable_via_api","booking_mode"]},"ProductCategory":{"type":"object","properties":{"id":{"type":"integer","example":9,"description":"The category, as in GET …/categories/{id}; list its products with GET …/products?category={id}"},"name":{"type":"string","example":"Accommodation","description":"In the response language (Content-Language)"}},"required":["id","name"],"description":"A storefront category a product is listed in"},"PriceTier":{"type":"object","properties":{"id":{"type":"integer","example":1,"description":"The key of this tier in a booking line's `participants`"},"name":{"type":"string","description":"In the language chosen with Accept-Language, falling back to the shop default","example":"Adults"},"category":{"type":["string","null"],"example":"ADULT","description":"A standard group such as ADULT or CHILD, when the shop has set one: for mapping tiers to other systems"},"min_age":{"type":["integer","null"],"description":"The youngest age the tier is for; null: no lower limit"},"max_age":{"type":["integer","null"],"description":"The oldest age the tier is for; null: no upper limit"}},"required":["id","name","category","min_age","max_age"]},"BookingMode":{"type":"string","enum":["buyable","event","transport","days","hours"]},"BookingOptions":{"type":"object","properties":{"product_id":{"type":"integer","description":"The product asked about"},"name":{"type":"string","description":"The product's name"},"bookable_via_api":{"type":"boolean","description":"False when the product can only be booked through `booking_url`"},"booking_url":{"type":"string","format":"uri","description":"The product on the shop's own storefront, where any product can be booked"},"modes":{"type":"array","items":{"$ref":"#/components/schemas/BookingMode"},"description":"How the product is booked; a product priced both by the day and by the hour has both"},"allow_multiday":{"type":"boolean","description":"One booking may cover several days: a daily booking then takes `nights` or `end_date`; otherwise its length is fixed"},"participant_pricing":{"type":"boolean","description":"Give `participants` as {pricetier_id: count}"},"ticket_activity":{"type":"boolean","description":"Booked with `tickets` on top of its mode"},"price_tiers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}},"required":["id","name"]},"description":"The product's price tiers: with `participant_pricing`, their ids are the keys of `participants`"},"rateplans":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"default":{"type":"boolean"}},"required":["id","title","default"]},"description":"Rate plans to choose from with `rateplan_id`; the `default` one applies when none is given"},"resource_pools":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"selectable":{"type":"boolean"},"resources":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"seats":{"type":"integer"},"min_participants":{"type":"integer"},"in_stock":{"type":"integer"}},"required":["id","name"]}}},"required":["id","name","selectable","resources"]},"description":"The pools of resources (rooms, boats, sizes and the like) the product uses. In a `selectable` pool the customer picks the resource: send it in `resources`"},"pool_choice":{"type":["object","null"],"properties":{"per_participant":{"type":"boolean"},"choices":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"free_places":{"type":"integer"}},"required":["id","name"]}},"hint":{"type":"string"}},"required":["per_participant","choices","hint"],"description":"Give `resource_pools`: one choice id per participant, or one for everyone"},"options":{"type":"array","items":{"type":"object","properties":{"product_id":{"type":"integer"},"name":{"type":"string"},"link_type":{"type":"string","enum":["mandatory","offer","optional","hidden"]},"automatic":{"type":"boolean","description":"Added by the shop; don't send it"},"required":{"type":"boolean"},"reservable":{"type":"boolean"},"count_selectable":{"type":"boolean","description":"The customer picks the count; otherwise it follows the main booking"},"optiongroup_id":{"type":["integer","null"]},"needs":{"type":"string","description":"What an options line for it needs, in plain English"},"form":{"anyOf":[{"$ref":"#/components/schemas/Form"},{"type":"null"}]}},"required":["product_id","name","link_type","automatic","required","reservable","count_selectable","optiongroup_id","needs","form"]},"description":"Option products linked to this one: send each as a line in the main line's `options`"},"option_groups":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"required":{"type":"boolean"},"choose":{"type":"string","enum":["one"]},"product_ids":{"type":"array","items":{"type":"integer"}}},"required":["id","name","required","choose","product_ids"]},"description":"Options of which the customer picks one; a required group needs a pick"},"packaged_products":{"type":"array","items":{"type":"object","properties":{"product_id":{"type":"integer"},"name":{"type":"string"},"reservable":{"type":"boolean"},"included":{"type":"boolean"},"count_per_participant":{"type":["integer","null"]},"resource_pools":{"type":["array","null"],"items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"free_places":{"type":"integer"}},"required":["id","name"]}}},"required":["product_id","name","reservable","included","count_per_participant","resource_pools"]},"description":"Products packaged with this one, booked in the line's `packages`: `included` ones come with it, the others are extras"},"packages_hint":{"type":["string","null"],"description":"How to fill `packages`, in plain English; null without packaged products"},"form":{"anyOf":[{"$ref":"#/components/schemas/Form"},{"type":"null"}],"description":"The product's booking form, answered in `form_response`; null when it has none"},"tickets":{"type":"array","items":{"type":"object","properties":{"product_id":{"type":"integer"},"name":{"type":"string"},"price":{"$ref":"#/components/schemas/Money"},"default":{"type":"boolean"}},"required":["product_id","name","price","default"]},"description":"Ticket activities: the ticket types"},"checked_for_participants":{"type":"integer","description":"The head count free places were checked for: `participants`, 1 when not given"},"free_dates":{"type":"array","items":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-24"},"description":"Days something can start, from `date` (or today) on"},"routes":{"type":"array","items":{"type":"object","properties":{"route_id":{"type":"integer"},"name":{"type":"string"},"direction":{"type":"string","enum":["outbound","return"]},"stops":{"type":"array","items":{"type":"object","properties":{"stop_id":{"type":"integer"},"name":{"type":"string"},"minutes_from_start":{"type":"integer"}},"required":["stop_id","name","minutes_from_start"]}}},"required":["route_id","name","direction","stops"]},"description":"Transport: the routes and their stops, for `origin` and `destination`"},"upcoming_shows":{"type":"array","items":{"$ref":"#/components/schemas/Show"},"description":"Events without a date: the next 90 days"},"shows":{"type":"array","items":{"$ref":"#/components/schemas/Show"},"description":"Events with a date: the shows starting that day"},"times":{"type":"object","properties":{"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-24"},"slots":{"type":"array","items":{"type":"object","properties":{"start_time":{"type":"string","pattern":"^\\d{2}:\\d{2}$","example":"14:30","description":"Local time in the shop timezone"},"end_times":{"type":"array","items":{"type":"string","pattern":"^\\d{2}:\\d{2}$","example":"14:30","description":"Local time in the shop timezone"}}},"required":["start_time","end_times"]}}},"required":["date","slots"],"description":"Bookings by the hour on `date`"},"departures":{"type":"object","properties":{"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-24"},"origin":{"type":"integer"},"destination":{"type":"integer"},"slots":{"type":"array","items":{"type":"object","properties":{"start_time":{"type":"string","pattern":"^\\d{2}:\\d{2}$","example":"14:30","description":"Local time in the shop timezone"},"end_times":{"type":"array","items":{"type":"string","pattern":"^\\d{2}:\\d{2}$","example":"14:30","description":"Local time in the shop timezone"}}},"required":["start_time","end_times"]},"description":"Departure times with their arrival times"}},"required":["date","origin","destination","slots"],"description":"Transport with a date, origin and destination: that day's departures"},"checkin":{"type":"object","properties":{"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-24"},"end_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-24"},"slots":{"type":"array","items":{"type":"object","properties":{"checkin_time":{"type":"string","pattern":"^\\d{2}:\\d{2}$","example":"14:30","description":"Local time in the shop timezone"},"checkout_times":{"type":"array","items":{"type":"string","pattern":"^\\d{2}:\\d{2}$","example":"14:30","description":"Local time in the shop timezone"}}},"required":["checkin_time","checkout_times"]}}},"required":["date","end_date","slots"],"description":"Daily bookings with set check-in times, given a date: the check-in times, with the check-out times each allows (`start_time` and `end_time` in the line)"},"pickup_places":{"type":"array","items":{"type":"object","properties":{"product_id":{"type":"integer"},"name":{"type":"string"},"role":{"type":"string","enum":["pickup","dropoff"]},"stop_id":{"type":["integer","null"]},"time":{"type":["string","null"],"pattern":"^\\d{2}:\\d{2}$","example":"14:30","description":"Local time in the shop timezone"},"available":{"type":"boolean"}},"required":["product_id","name","role","stop_id","time","available"]},"description":"With a date and start_time: the pick-up and drop-off places. Send the chosen one as an options line with its `product_id` and `stop_id`"},"hints":{"type":"array","items":{"type":"string"},"description":"What to give next, in plain English"}},"required":["product_id","name","bookable_via_api","booking_url","modes","allow_multiday","participant_pricing","ticket_activity","price_tiers","rateplans","resource_pools","pool_choice","options","option_groups","packaged_products","packages_hint","form","checked_for_participants","hints"]},"Form":{"type":"object","properties":{"form_id":{"type":"integer","description":"The form's id in the shop"},"name":{"type":"string","description":"The form's name"},"fields":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","description":"The key of this field's answer in the line's `form_response`"},"type":{"type":"string","example":"text","description":"text, textarea, select, checkbox and the like"},"required":{"type":"boolean"},"options":{"type":["array","null"],"items":{"type":"string"},"description":"Selects: the allowed answers"}},"required":["title","type","required","options"]},"description":"The questions, answered in the line's `form_response`"}},"required":["form_id","name","fields"]},"Show":{"type":"object","properties":{"show_id":{"type":"integer","description":"Send as `show_id` in a booking line"},"start":{"type":"string","example":"2026-12-24T14:30:00+02:00","description":"ISO 8601 with offset"},"end":{"type":"string","example":"2026-12-24T14:30:00+02:00","description":"ISO 8601 with offset"},"seatmap":{"type":"boolean","description":"Seats are chosen from GET …/shows/{id}/seatmap and sent as `seat_ids`"},"on_sale":{"type":"boolean","description":"False when the shop has marked the show upcoming or hidden it from online sales"},"free_places":{"type":["integer","null"],"description":"Places left at the venue; null when the show has no venue"},"bookable":{"type":"boolean","description":"On sale and with room for the participants asked about"},"tickets":{"type":"array","items":{"type":"object","properties":{"product_id":{"type":"integer"},"name":{"type":"string"},"price":{"$ref":"#/components/schemas/Money"},"default":{"type":"boolean"}},"required":["product_id","name","price","default"]},"description":"The show's ticket types and prices; send counts in `tickets`"}},"required":["show_id","start","end","seatmap","on_sale","free_places","bookable","tickets"]},"Availability":{"type":"object","properties":{"product_id":{"type":"integer","description":"The product asked about"},"from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-24","description":"The first day checked"},"to":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-24","description":"The last day checked"},"participants":{"type":"integer","description":"The head count checked for"},"free_dates":{"type":"array","items":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-24"},"description":"Days something can start for that many participants"}},"required":["product_id","from","to","participants","free_dates"]},"Seatmap":{"type":"object","properties":{"show_id":{"type":"integer","description":"The show the seats are for"},"width":{"type":["number","null"],"description":"The width of the drawing, in the units of the seats' x, y, w and h"},"height":{"type":["number","null"],"description":"The height of the drawing, in the same units"},"seats":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Send in `seat_ids`"},"row":{"type":["string","null"],"description":"The row label shown with the seat"},"number":{"type":["string","null"],"description":"The label of the seat"},"zone":{"type":["integer","null"],"description":"The price zone, when the venue has zones"},"x":{"type":"number","description":"Left edge"},"y":{"type":"number","description":"Top edge"},"w":{"type":"number","description":"Width"},"h":{"type":"number","description":"Height"},"available":{"type":"boolean","description":"False when taken for this show, disabled, or kept free for distancing"}},"required":["id","row","number","zone","x","y","w","h","available"]},"description":"The venue's seats, each with whether it can be booked"}},"required":["show_id","width","height","seats"]},"Quote":{"type":"object","properties":{"lines":{"type":"array","items":{"$ref":"#/components/schemas/PricedLine"},"description":"The request's lines as priced, in order"},"total":{"$ref":"#/components/schemas/Money"},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/Warning"},"description":"Notes on the lines that don't stop them being booked"}},"required":["lines","total","warnings"],"description":"Lines that can't be booked as given answer 422 with the booking engine's code instead"},"PricedLine":{"allOf":[{"$ref":"#/components/schemas/LineSummary"},{"type":"object","properties":{"total":{"$ref":"#/components/schemas/Money"},"items":{"type":"array","items":{"$ref":"#/components/schemas/PricedItem"},"description":"The order rows the line becomes: the product, its options, tickets and the like"}},"required":["total","items"]}]},"PricedItem":{"type":"object","properties":{"product_id":{"type":["integer","null"],"description":"The product of this row; null for rows without one"},"name":{"type":"string","description":"The row as the order will show it"},"quantity":{"type":"number","description":"How many of `unit_price` the row is"},"unit_price":{"$ref":"#/components/schemas/Money"},"vat_rate":{"type":"number","example":14,"description":"Percent; prices include VAT"},"total":{"$ref":"#/components/schemas/Money"}},"required":["product_id","name","quantity","unit_price","vat_rate","total"]},"LineSummary":{"type":"object","properties":{"index":{"type":"integer","description":"Position of the line in the request"},"product_id":{"type":["integer","null"],"description":"The product booked"},"name":{"type":["string","null"],"description":"The product's name"},"mode":{"anyOf":[{"$ref":"#/components/schemas/BookingMode"},{"type":"null"}],"description":"How the line was booked"},"date":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-24","description":"The start day"},"end_date":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-24","description":"The end day, such as the check-out day of a daily booking; null when the line ends on `date`"},"start_time":{"type":["string","null"],"pattern":"^\\d{2}:\\d{2}$","example":"14:30","description":"Local time in the shop timezone"},"end_time":{"type":["string","null"],"pattern":"^\\d{2}:\\d{2}$","example":"14:30","description":"Local time in the shop timezone"},"show_id":{"type":["integer","null"],"description":"Events: the show booked"},"participants":{"type":["integer","null"],"description":"The head count"},"count":{"type":["integer","null"],"description":"The quantity, for products bought or booked by count"}},"required":["index","product_id","name","mode","date","end_date","start_time","end_time","show_id","participants","count"]},"Warning":{"type":"object","properties":{"line":{"type":["integer","null"],"description":"Index of the line it concerns"},"code":{"type":["string","null"],"description":"Machine-readable, when the engine gives one"},"message":{"type":"string","description":"A readable explanation"}},"required":["line","code","message"]},"QuoteRequest":{"type":"object","properties":{"lines":{"type":"array","items":{"$ref":"#/components/schemas/CartLine"},"minItems":1,"maxItems":50,"description":"Up to 50 lines: things to book, and discount codes, which apply to the lines before them"}},"required":["lines"]},"CartLine":{"anyOf":[{"$ref":"#/components/schemas/BookingLine"},{"$ref":"#/components/schemas/DiscountCodeLine"}]},"BookingLine":{"type":"object","properties":{"product_id":{"type":"integer","exclusiveMinimum":0,"description":"The product to book: an `id` from GET …/products"},"count":{"type":"integer","minimum":1,"description":"Quantity of a buyable product, or of units for unit-based bookings"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-24","description":"The start day, in the shop's timezone: of a daily or hourly booking, or the outbound trip of a transport"},"end_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-24","description":"Check-out day of a daily booking (or give `nights`)"},"nights":{"type":"integer","minimum":1,"description":"Daily bookings: how many nights (or give `end_date`)"},"start_time":{"type":"string","pattern":"^\\d{2}:\\d{2}$","example":"14:30","description":"Local time in the shop timezone"},"end_time":{"type":"string","pattern":"^\\d{2}:\\d{2}$","example":"14:30","description":"Or give `duration`"},"duration":{"type":"integer","minimum":1,"description":"Minutes"},"participants":{"anyOf":[{"type":"integer","minimum":1},{"type":"object","additionalProperties":{"type":"integer","minimum":0},"description":"{pricetier_id: count}","example":{"12":2,"13":1}}],"description":"A head count, or counts per price tier (see `pricetiers` in booking options)"},"resource_count":{"type":"integer","minimum":1,"description":"How many resources (rooms, boats and the like) the participants are spread over; by default the fewest that fit them"},"resources":{"type":"object","additionalProperties":{"type":"array","items":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"type":"object","properties":{"id":{"type":"integer","exclusiveMinimum":0},"seats":{"type":"integer","minimum":1}},"required":["id","seats"]}]}},"description":"{pool_id: [resource_id | {id, seats}]}: only when the product lets the customer choose (see `pool_choice`)"},"resource_pools":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"type":"array","items":{"type":"integer","exclusiveMinimum":0}}],"description":"Choices from `pool_choice`: one id per participant, or one id for everyone"},"preferred_resource":{"type":"integer","exclusiveMinimum":0,"description":"A resource (from `resource_pools` in booking options) to prefer when the booking is placed"},"rateplan_id":{"type":"integer","exclusiveMinimum":0,"description":"One of `rateplans` in booking options; the default plan otherwise"},"show_id":{"type":"integer","exclusiveMinimum":0,"description":"Events: one of `shows` / `upcoming_shows` in booking options"},"seat_ids":{"type":"array","items":{"type":"integer","exclusiveMinimum":0},"description":"Events with a seat map: seats from GET …/shows/{id}/seatmap"},"tickets":{"type":"object","additionalProperties":{"type":"integer","minimum":0},"description":"{ticket_product_id: count} for ticket activities and events with ticket types"},"origin":{"type":"integer","exclusiveMinimum":0,"description":"Transport: departure stop id from `routes`"},"destination":{"type":"integer","exclusiveMinimum":0,"description":"Transport: arrival stop id from `routes`"},"return":{"type":"object","properties":{"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-24"},"time":{"type":"string","pattern":"^\\d{2}:\\d{2}$","example":"14:30","description":"Local time in the shop timezone"}},"required":["date","time"],"description":"Transport: the return departure"},"stop_id":{"type":"integer","exclusiveMinimum":0,"description":"Options that are pick-up or drop-off places: the chosen stop, from `pickup_places` in booking options (asked with date and start_time)"},"packages":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","maxLength":100,"description":"The participant's name, shown on the booking"},"products":{"type":"array","items":{"type":"object","properties":{"product_id":{"type":"integer","exclusiveMinimum":0},"count":{"type":"integer","minimum":1,"description":"Extras that aren't included: how many"},"resource_pools":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"type":"array","items":{"type":"integer","exclusiveMinimum":0}}],"description":"A packaged product with `resource_pools` in booking options (e.g. sizes): the chosen one, or a list for several selectors"}},"required":["product_id"]}}},"required":["products"]},"description":"Products packaged with this one (`packaged_products`): one entry per participant, see `packages_hint`"},"form_response":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]},"description":"Answers to the product form (see `form` in booking options), keyed by field title; checkboxes \"1\" or \"0\""},"options":{"type":"array","items":{"$ref":"#/components/schemas/BookingLine"},"description":"Option products linked to this product, each a line of its own"}},"required":["product_id"],"description":"One thing to book. Which fields are needed depends on the product's booking mode: read GET …/products/{id}/booking-options first; its `modes` and `hints` say what to give."},"DiscountCodeLine":{"type":"object","properties":{"discount_code":{"type":"string","minLength":1,"maxLength":64,"example":"SUMMER25","description":"The code as the customer has it"}},"required":["discount_code"],"description":"A discount or campaign code. It applies to the lines before it."},"Cart":{"type":"object","properties":{"id":{"type":"string","example":"crt_8f3k2m9q1x7v4b6nQ2wE5rT7","description":"For …/carts/{id} and its checkout"},"status":{"type":"string","enum":["active","checkout","ordered","released","expired"],"description":"active: places held; checkout: the customer is in the shop's checkout; ordered: the order was made; released or expired: the places are free again"},"hold_until":{"type":["string","null"],"example":"2026-12-24T14:30:00+02:00","description":"The places are held until then"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/PricedLine"},"description":"The lines as last priced; empty once the cart is released or expired"},"total":{"$ref":"#/components/schemas/Money"},"order_id":{"type":["integer","null"],"description":"Set once the customer has ordered"},"created_at":{"type":"string","example":"2026-12-24T14:30:00+02:00","description":"ISO 8601 with offset"},"updated_at":{"type":"string","example":"2026-12-24T14:30:00+02:00","description":"ISO 8601 with offset"}},"required":["id","status","hold_until","lines","total","order_id","created_at","updated_at"]},"CartRequest":{"type":"object","properties":{"lines":{"type":"array","items":{"$ref":"#/components/schemas/CartLine"},"minItems":1,"maxItems":50,"description":"Up to 50 lines: things to book, and discount codes, which apply to the lines before them"}},"required":["lines"]},"Checkout":{"type":"object","properties":{"checkout_url":{"type":"string","format":"uri","example":"https://johkula.johku.com/fi/checkout?handoff=…","description":"Send the customer here to pay in the shop's own checkout"},"expires_at":{"type":"string","example":"2026-12-24T14:30:00+02:00","description":"The link works once, until then"}},"required":["checkout_url","expires_at"]},"CheckoutRequest":{"type":"object","properties":{"return_url":{"type":"string","pattern":"^https:\\/\\/","description":"Where the shop sends the customer back after paying (https): its confirmation page shows a link and goes there after 10 seconds, unless the customer chooses to stay. Add your own reference to it if you need one."}},"required":["return_url"]},"Booking":{"type":"object","properties":{"order_id":{"type":"integer","description":"The order made in the shop: GET …/orders/{order_id}"},"reference":{"type":"string","description":"Your reference, as sent"},"status":{"type":"string","enum":["confirmed"],"description":"Always confirmed: the places are booked"},"existing":{"type":"boolean","description":"True when a booking with this reference already existed and was returned as is"},"total":{"$ref":"#/components/schemas/Money"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/LineSummary"},"description":"What each request line booked"},"reservation_ids":{"type":"array","items":{"type":"integer"},"description":"The reservations made, as GET …/reservations lists them"},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/Warning"},"description":"Notes on the lines that didn't stop the booking"},"created_at":{"type":["string","null"],"example":"2026-12-24T14:30:00+02:00","description":"ISO 8601 with offset"}},"required":["order_id","reference","status","existing","total","lines","reservation_ids","warnings","created_at"]},"BookingRequest":{"type":"object","properties":{"reference":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[\\x21-\\x7e]+$","description":"Your own booking reference (printable ASCII, no spaces): a repeated reference returns the existing booking"},"customer":{"$ref":"#/components/schemas/CustomerInput"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/CartLine"},"minItems":1,"maxItems":50,"description":"Up to 50 lines: things to book, and discount codes, which apply to the lines before them"},"notes":{"type":"string","maxLength":2000,"description":"A note to the shop, saved on the order"}},"required":["reference","customer","lines"]},"CustomerInput":{"type":"object","properties":{"first_name":{"type":"string","maxLength":100,"description":"The customer's first name"},"last_name":{"type":"string","maxLength":100,"description":"The customer's last name"},"email":{"type":"string","maxLength":200,"format":"email","description":"The customer's email address"},"phone":{"type":"string","maxLength":40,"example":"+358401234567","description":"The customer's phone number"},"company":{"type":"string","maxLength":200,"description":"The company, for a business customer"},"address":{"type":"string","maxLength":200,"description":"Street address"},"postal_code":{"type":"string","maxLength":20,"example":"33100","description":"Postal code"},"city":{"type":"string","maxLength":100,"example":"Tampere","description":"City"},"country":{"type":"string","minLength":2,"maxLength":2,"example":"FI","description":"ISO 3166-1 alpha-2"}},"required":["first_name","last_name","email"],"description":"Who a confirmed booking is for: the order is made in this name"},"OrderPage":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OrderSummary"},"description":"The items on this page"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page"}},"required":["data","next_cursor"]},"OrderSummary":{"type":"object","properties":{"id":{"type":"integer","description":"For GET …/orders/{id}"},"status":{"$ref":"#/components/schemas/OrderStatus"},"total":{"$ref":"#/components/schemas/Money"},"customer_name":{"type":["string","null"],"description":"The customer's name as on the order"},"channel":{"type":["string","null"],"example":"johkula","description":"Where the order came from: the shop id for its web shop, manual, open, a partner channel"},"reference":{"type":["string","null"],"description":"Your reference, on bookings you made with POST …/bookings"},"created_at":{"type":["string","null"],"example":"2026-12-24T14:30:00+02:00","description":"ISO 8601 with offset"},"updated_at":{"type":["string","null"],"example":"2026-12-24T14:30:00+02:00","description":"Last change; null on orders from before change tracking"}},"required":["id","status","total","customer_name","channel","reference","created_at","updated_at"]},"OrderStatus":{"type":"string","enum":["open","pending","confirmed","paid","refunded"],"description":"open: a booking request the shop confirms later; pending: waiting for payment; confirmed: billed later; paid; refunded"},"Order":{"type":"object","properties":{"id":{"type":"integer","description":"The order's id in the shop"},"status":{"$ref":"#/components/schemas/OrderStatus"},"total":{"$ref":"#/components/schemas/Money"},"vat_total":{"$ref":"#/components/schemas/Money"},"channel":{"type":["string","null"],"example":"johkula","description":"Where the order came from: the shop id for its web shop, manual, open, a partner channel"},"reference":{"type":["string","null"],"description":"Your reference, on bookings you made with POST …/bookings"},"customer":{"type":"object","properties":{"name":{"type":["string","null"]},"company":{"type":["string","null"]},"email":{"type":["string","null"]},"phone":{"type":["string","null"]}},"required":["name","company","email","phone"],"description":"The customer as on the order; a field is null when not given"},"lines":{"type":"array","items":{"type":"object","properties":{"product_id":{"type":["integer","null"]},"name":{"type":"string"},"quantity":{"type":"number"},"unit_price":{"$ref":"#/components/schemas/Money"},"total":{"$ref":"#/components/schemas/Money"},"vat_rate":{"type":"number"}},"required":["product_id","name","quantity","unit_price","total","vat_rate"]},"description":"The order rows, prices VAT included"},"reservations":{"type":"array","items":{"$ref":"#/components/schemas/Reservation"},"description":"What the order booked, as GET …/reservations lists it"},"created_at":{"type":["string","null"],"example":"2026-12-24T14:30:00+02:00","description":"ISO 8601 with offset"},"updated_at":{"type":["string","null"],"example":"2026-12-24T14:30:00+02:00","description":"ISO 8601 with offset"}},"required":["id","status","total","vat_total","channel","reference","customer","lines","reservations","created_at","updated_at"],"description":"An order with its rows and reservations. `total` includes VAT; `vat_total` is the VAT in it."},"Reservation":{"type":"object","properties":{"id":{"type":"integer","description":"The reservation's id in the shop"},"order_id":{"type":["integer","null"],"description":"The order it belongs to: GET …/orders/{order_id}; null when it has none"},"product_id":{"type":["integer","null"],"description":"The product booked"},"product_name":{"type":["string","null"],"description":"The product's name"},"start":{"type":["string","null"],"example":"2026-12-24T14:30:00+02:00","description":"ISO 8601 with offset"},"end":{"type":["string","null"],"example":"2026-12-24T14:30:00+02:00","description":"ISO 8601 with offset"},"participants":{"type":["integer","null"],"description":"The head count"},"resource_count":{"type":["integer","null"],"description":"How many resources (rooms, boats and the like) it takes"},"resources":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}},"required":["id","name"]},"description":"The resources it is placed on"},"status":{"type":"string","enum":["tentative","confirmed"],"description":"tentative: still in a basket or awaiting payment"},"checked_in":{"type":"boolean","description":"The shop has checked the customer in"},"customer":{"type":"object","properties":{"name":{"type":["string","null"]},"email":{"type":["string","null"]},"phone":{"type":["string","null"]}},"required":["name","email","phone"],"description":"The customer of the reservation's order"}},"required":["id","order_id","product_id","product_name","start","end","participants","resource_count","resources","status","checked_in","customer"]},"OrderLookup":{"type":"object","properties":{"code":{"type":"string","pattern":"^[0-9a-f]{32}(@\\d{1,4})?$","example":"37f80c34229f338171d83559051b0bbe","description":"The order's code as the customer has it: 32 hex characters, on a payment plan's later payments followed by @ and a number"}},"required":["code"]},"ReservationPage":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Reservation"},"description":"The items on this page"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page"}},"required":["data","next_cursor"]},"CustomerPage":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Customer"},"description":"The items on this page"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page"}},"required":["data","next_cursor"]},"Customer":{"type":"object","properties":{"id":{"type":"integer","description":"For GET …/customers/{id}"},"name":{"type":["string","null"],"description":"The name as the shop has it, in one field"},"company":{"type":["string","null"],"description":"The company, for a business customer"},"email":{"type":["string","null"],"description":"The customer's email address"},"phone":{"type":["string","null"],"description":"The customer's phone number"},"address":{"type":"object","properties":{"street":{"type":["string","null"]},"postal_code":{"type":["string","null"]},"city":{"type":["string","null"]},"country":{"type":["string","null"],"description":"ISO 3166-1 alpha-2"}},"required":["street","postal_code","city","country"],"description":"The postal address; a field is null when not given"},"marketing_consent":{"type":"boolean","description":"The customer has agreed to receive marketing from the shop"}},"required":["id","name","company","email","phone","address","marketing_consent"]},"ReportJob":{"type":"object","properties":{"id":{"type":"string","example":"6a0f3c2e9b1d4f7a8c5e2b0d1f3a5c7e","description":"Poll GET …/reports/{id} with it until the report is done or failed"},"status":{"$ref":"#/components/schemas/ReportStatus"}},"required":["id","status"]},"ReportStatus":{"type":"string","enum":["queued","running","done","failed"],"description":"queued and running: ask again in a moment; done: the report's `result` is set; failed: request a new report"},"ReportRequest":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ReportType"},"from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-24","description":"The first day, in the shop's timezone"},"to":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-24","description":"At most 366 days after `from`; both days included"}},"required":["type","from","to"]},"ReportType":{"type":"string","enum":["sales","channel_sales"],"description":"sales: totals by product; channel_sales: totals by sales channel (web shop, each POS, admin, partners)"},"Report":{"type":"object","properties":{"id":{"type":"string","description":"The report's id"},"status":{"$ref":"#/components/schemas/ReportStatus"},"type":{"anyOf":[{"$ref":"#/components/schemas/ReportType"},{"type":"null"}],"description":"Known once the report is done"},"result":{"type":["object","null"],"properties":{"totals":{"type":"object","properties":{"gross":{"$ref":"#/components/schemas/Money"},"net":{"$ref":"#/components/schemas/Money"},"vat":{"$ref":"#/components/schemas/Money"}},"required":["gross","net","vat"],"description":"Sales less refunds and discounts"},"sales":{"type":"object","properties":{"count":{"type":"number"},"gross":{"$ref":"#/components/schemas/Money"},"net":{"$ref":"#/components/schemas/Money"},"vat":{"$ref":"#/components/schemas/Money"}},"required":["count","gross","net","vat"]},"refunds":{"type":"object","properties":{"count":{"type":"number"},"gross":{"$ref":"#/components/schemas/Money"},"net":{"$ref":"#/components/schemas/Money"},"vat":{"$ref":"#/components/schemas/Money"}},"required":["count","gross","net","vat"]},"discounts":{"type":"object","properties":{"count":{"type":"number"},"gross":{"$ref":"#/components/schemas/Money"},"net":{"$ref":"#/components/schemas/Money"},"vat":{"$ref":"#/components/schemas/Money"}},"required":["count","gross","net","vat"]},"rows":{"type":"array","items":{"type":"object","properties":{"count":{"type":"number"},"gross":{"$ref":"#/components/schemas/Money"},"net":{"$ref":"#/components/schemas/Money"},"vat":{"$ref":"#/components/schemas/Money"},"key":{"type":"string","description":"sales: the product id (or a name for rows without a product); channel_sales: the channel"},"name":{"type":"string"}},"required":["count","gross","net","vat","key","name"]},"description":"Sales per product or per channel"},"truncated":{"type":"boolean","description":"True when rows holds only the first part; narrow the range for all"}},"required":["totals","sales","refunds","discounts","rows","truncated"],"description":"Set once status is done"}},"required":["id","status","type","result"]},"AccessRequest":{"type":"object","properties":{"id":{"type":"string","description":"The connection's id; once approved, GET /v1/connections lists it with the same id"},"shop":{"type":"string","description":"The shop asked"},"scopes":{"type":"array","items":{"$ref":"#/components/schemas/ShopScope"},"description":"The scopes asked for; the shop approves or denies them together"},"reason":{"type":"string","description":"As you sent it"},"status":{"$ref":"#/components/schemas/ConnectionStatus"},"requested_at":{"type":"string","example":"2026-12-24T14:30:00+02:00","description":"ISO 8601 with offset"},"decided_at":{"type":["string","null"],"example":"2026-12-24T14:30:00+02:00","description":"ISO 8601 with offset"}},"required":["id","shop","scopes","reason","status","requested_at","decided_at"]},"ShopScope":{"type":"string","enum":["catalog:read","availability:read","booking:write","booking:confirm","orders:read","customers:read","reports:read"]},"ConnectionStatus":{"type":"string","enum":["requested","active","denied","revoked","paused"],"description":"requested: an access request waiting for the shop; active: the shop's data is available with the granted scopes; denied: the shop turned the request down; revoked: the connection was ended. paused: the shop's Johku plan doesn't include the partner API right now. The connection resumes by itself, with its scopes, when the plan does again."},"AccessRequestInput":{"type":"object","properties":{"shop":{"type":"string","pattern":"^[A-Za-z0-9_]{1,64}$","example":"johkula","description":"The shop to ask: its id, the subdomain of its storefront"},"scopes":{"type":"array","items":{"$ref":"#/components/schemas/ShopScope"},"minItems":1,"description":"The scopes you ask the shop to grant"},"reason":{"type":"string","minLength":10,"maxLength":1000,"description":"Shown to the shop's admins with your integration's name"}},"required":["shop","scopes","reason"]},"AccessRequestList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AccessRequest"},"description":"Newest first"}},"required":["data"]},"ConnectionList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Connection"},"description":"Active and paused connections; requests still waiting are in GET /v1/access-requests"}},"required":["data"]},"Connection":{"type":"object","properties":{"id":{"type":"string","description":"The connection's id"},"shop":{"type":"string","example":"johkula","description":"The shop id, for /v1/shops/{shop}/…"},"shop_name":{"type":["string","null"],"description":"The shop's name"},"scopes":{"type":"array","items":{"$ref":"#/components/schemas/ShopScope"},"description":"What the shop has granted your integration"},"status":{"$ref":"#/components/schemas/ConnectionStatus"},"method":{"type":"string","enum":["self_connect","request"],"description":"self_connect: the shop connected your integration itself; request: it approved your access request"},"connected_at":{"type":["string","null"],"example":"2026-12-24T14:30:00+02:00","description":"ISO 8601 with offset"},"last_used_at":{"type":["string","null"],"example":"2026-12-24T14:30:00+02:00","description":"ISO 8601 with offset"}},"required":["id","shop","shop_name","scopes","status","method","connected_at","last_used_at"]},"AtlasProductPage":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AtlasProductSummary"},"description":"The matching products on this page, in the order of `sort`"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page"},"total":{"type":"integer","description":"Matching products, counting at most the first 250 ranked results"},"context":{"$ref":"#/components/schemas/AtlasSearchContext"}},"required":["data","next_cursor","total","context"]},"AtlasProductSummary":{"type":"object","properties":{"id":{"type":"string","example":"48213","description":"The Atlas id, for GET /v1/atlas/products/{id} and proposals"},"shop":{"type":"string","example":"johkula","description":"The shop id, for the shop's own endpoints (/v1/shops/{shop}/…)"},"shop_name":{"type":"string","description":"The shop's name"},"product_id":{"type":"integer","example":259,"description":"The product's id in its shop: GET /v1/shops/{shop}/products/{product_id}"},"name":{"type":"string","description":"The product's name"},"type":{"anyOf":[{"type":"string","example":"accommodation","description":"One of GET /v1/atlas/product-types"},{"type":"null"}],"description":"The product type; null when it has none"},"location":{"anyOf":[{"$ref":"#/components/schemas/AtlasLocation"},{"type":"null"}],"description":"Where the product is; null when unknown"},"distance_km":{"type":["number","null"],"description":"From the searched place; null without one"},"postarea":{"type":["string","null"],"example":"Tampere","description":"The postal area of the location"},"from_price":{"anyOf":[{"$ref":"#/components/schemas/Money"},{"type":"null"}],"description":"The public from-price; null when the shop hides prices or has none"},"duration_minutes":{"type":["integer","null"],"description":"How long it lasts; null when not set"},"attributes":{"type":"array","items":{"type":"string"},"example":["sauna","lakeside"],"description":"Amenities and features, as the `attributes` filter matches them"},"image_url":{"type":["string","null"],"format":"uri","description":"A thumbnail of the main image"},"booking_url":{"type":["string","null"],"format":"uri","description":"The product on the shop's storefront"},"availability":{"anyOf":[{"$ref":"#/components/schemas/AtlasAvailability"},{"type":"null"}],"description":"Only when the request had dates"},"stay_total":{"anyOf":[{"$ref":"#/components/schemas/Money"},{"type":"null"}],"description":"What the requested dates cost on the storefront, when bookable"}},"required":["id","shop","shop_name","product_id","name","type","location","distance_km","postarea","from_price","duration_minutes","attributes","image_url","booking_url","availability","stay_total"]},"AtlasLocation":{"type":"object","properties":{"lat":{"type":"number","example":61.4978,"description":"Latitude, WGS 84"},"lng":{"type":"number","example":23.761,"description":"Longitude, WGS 84"},"source":{"type":"string","enum":["product","company"],"description":"product: the product's own location; company: the shop's address"}},"required":["lat","lng","source"]},"AtlasAvailability":{"type":"object","properties":{"bookable":{"type":"boolean","description":"Accommodation: every night of the stay is free; other products: some day in the range has room"},"mode":{"type":"string","enum":["full_stay","any_day"],"description":"full_stay: accommodation searched with both dates, every night checked; any_day: some day in the range is enough"},"nights":{"type":["integer","null"],"description":"full_stay: the nights of the stay"},"first_available":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-24"},{"type":"null"}],"description":"The first day in the range with room"},"next_available":{"anyOf":[{"type":"object","properties":{"start_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-24"},"end_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-24"},"nights":{"type":"integer"}},"required":["start_date","end_date","nights"]},{"type":"null"}],"description":"When not bookable: the next free stay (or activity day) within 90 days, if any"}},"required":["bookable","mode","nights","first_available","next_available"]},"AtlasSearchContext":{"type":"object","properties":{"place":{"anyOf":[{"type":"object","properties":{"name":{"type":["string","null"]},"lat":{"type":"number"},"lng":{"type":"number"},"radius_km":{"type":["number","null"]}},"required":["name","lat","lng","radius_km"]},{"type":"null"}],"description":"How `place` or lat/lng was understood"},"hint":{"type":["string","null"],"description":"Why a result is empty, or how a filter was read"}},"required":["place","hint"],"description":"How the search was understood"},"AtlasProduct":{"allOf":[{"$ref":"#/components/schemas/AtlasProductSummary"},{"type":"object","properties":{"description":{"type":["string","null"],"description":"Plain text summary"},"long_description":{"type":["string","null"],"description":"The full description as plain text"},"street_address":{"type":["string","null"]},"images":{"type":"array","items":{"$ref":"#/components/schemas/AtlasImage"},"description":"The main image first"},"languages":{"type":"array","items":{"type":"string"}},"suitability":{"type":"array","items":{"type":"string"}},"difficulty":{"type":["string","null"]},"shoretype":{"type":["string","null"]},"rate_plans":{"type":"array","items":{"$ref":"#/components/schemas/AtlasRatePlan"},"description":"With dates: each rate plan's total"},"pickup_places":{"type":"array","items":{"$ref":"#/components/schemas/AtlasPickupPlace"}}},"required":["description","long_description","street_address","images","languages","suitability","difficulty","shoretype","rate_plans","pickup_places"]}]},"AtlasImage":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"The full-size image"},"thumbnail_url":{"type":["string","null"],"format":"uri","description":"A smaller version for lists"},"is_main":{"type":"boolean","description":"The product's main image"},"title":{"type":["string","null"],"description":"The title the shop gave the image, if any"},"alt":{"type":["string","null"],"description":"Alternative text for screen readers, if the shop wrote one"}},"required":["url","thumbnail_url","is_main","title","alt"]},"AtlasRatePlan":{"type":"object","properties":{"id":{"type":"string","description":"The rate plan's id in the shop"},"name":{"type":"string","description":"The rate plan's name"},"is_default":{"type":"boolean","description":"The product's default rate plan"},"stay_total":{"anyOf":[{"$ref":"#/components/schemas/Money"},{"type":"null"}],"description":"What the requested dates cost with this plan; null without dates or when it can't be priced for them"},"booking_url":{"type":["string","null"],"format":"uri","description":"Opens the product with this rate plan chosen"}},"required":["id","name","is_default","stay_total","booking_url"]},"AtlasPickupPlace":{"type":"object","properties":{"role":{"type":"string","enum":["pickup","dropoff"],"description":"pickup: the customer is picked up here; dropoff: dropped off here"},"name":{"type":"string","description":"The place's name"},"address":{"type":["string","null"],"description":"The street address; null when not set"},"lat":{"type":["number","null"],"description":"Latitude, WGS 84"},"lng":{"type":["number","null"],"description":"Longitude, WGS 84"},"minutes_before_start":{"type":["integer","null"],"description":"How many minutes before the start the customer should be at the place; null when not set"},"required":{"type":"boolean","description":"Booking the product needs a choice among these places"}},"required":["role","name","address","lat","lng","minutes_before_start","required"]},"AtlasCompany":{"type":"object","properties":{"shop":{"type":"string","example":"johkula","description":"The shop id, for the shop's own endpoints (/v1/shops/{shop}/…)"},"name":{"type":"string","description":"The shop's name"},"description":{"type":["string","null"],"description":"What the company says about itself, as plain text"},"website":{"type":["string","null"],"description":"The company's own website"},"storefront_url":{"type":["string","null"],"format":"uri","description":"The shop's web shop on Johku"},"address":{"type":["string","null"],"description":"The street address, on one line"},"location":{"anyOf":[{"type":"object","properties":{"lat":{"type":"number"},"lng":{"type":"number"}},"required":["lat","lng"]},{"type":"null"}],"description":"Where the company is, WGS 84; null when unknown"},"products":{"type":"array","items":{"$ref":"#/components/schemas/AtlasProductSummary"},"description":"Bookable products the shop shows on its storefront"},"extras":{"type":"array","items":{"$ref":"#/components/schemas/AtlasProductSummary"},"description":"Add-ons such as cleaning or gift cards"}},"required":["shop","name","description","website","storefront_url","address","location","products","extras"]},"AtlasProductTypeList":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string","example":"accommodation","description":"One of GET /v1/atlas/product-types"},"label":{"type":"string"},"also_matches":{"type":"array","items":{"type":"string"},"description":"Types the filter includes too"}},"required":["value","label","also_matches"]},"description":"Every product type, for the `type` filter"}},"required":["data"]},"AtlasProposal":{"type":"object","properties":{"proposals":{"type":"array","items":{"type":"object","properties":{"shop":{"type":"string"},"shop_name":{"type":"string"},"url":{"type":"string","format":"uri","description":"A private page on the shop's storefront with the products; nothing is held until the customer adds them to the basket there"},"expires_at":{"type":"string","description":"ISO 8601"},"products":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"start_date":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-24"},"end_date":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-24"},"start_time":{"type":["string","null"]},"participants":{"type":["integer","null"]},"units":{"type":["integer","null"]},"availability":{"anyOf":[{"$ref":"#/components/schemas/AtlasAvailability"},{"type":"null"}]}},"required":["id","name","start_date","end_date","start_time","participants","units","availability"]}}},"required":["shop","shop_name","url","expires_at","products"]},"description":"One per shop"},"skipped":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"reason":{"type":"string"}},"required":["id","reason"]},"description":"Items left out of the proposals, with the reason"}},"required":["proposals","skipped"]},"AtlasProposalInput":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":64,"description":"An Atlas product id"},"start_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-24"},"end_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-24"},"start_time":{"type":"string","pattern":"^\\d{2}:\\d{2}$","example":"12:00"},"participants":{"type":"integer","exclusiveMinimum":0,"maximum":1000},"units":{"type":"integer","exclusiveMinimum":0,"maximum":1000}},"required":["id"]},"minItems":1,"maxItems":20,"description":"The products to propose, 1 to 20; products of the same shop share one proposal"},"locale":{"type":"string","pattern":"^[a-z]{2}-[A-Z]{2}$","example":"fi-FI","description":"The storefront language; each shop's default otherwise"}},"required":["items"]}},"parameters":{}},"paths":{"/v1/me":{"get":{"operationId":"getMe","tags":["Meta"],"summary":"The partner, integration and key making this request, with its limits","description":"The shops your integration is connected to are listed by GET /v1/connections.","responses":{"200":{"description":"Who you are","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}},"400":{"description":"The request is not valid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"VALIDATION_FAILED":{"summary":"VALIDATION_FAILED","value":{"type":"https://api.johku.com/problems/validation-failed","status":400,"code":"VALIDATION_FAILED","title":"The request is not valid","errors":[{"path":"limit","code":"TOO_BIG","message":"Too big: expected number to be <=100"}]}}}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"INVALID_KEY":{"summary":"INVALID_KEY","value":{"type":"https://api.johku.com/problems/invalid-key","status":401,"code":"INVALID_KEY","title":"The API key is not valid"}}}}}},"403":{"description":"The key, integration or shop connection does not allow this","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"SCOPE_NOT_GRANTED":{"summary":"SCOPE_NOT_GRANTED","value":{"type":"https://api.johku.com/problems/scope-not-granted","status":403,"code":"SCOPE_NOT_GRANTED","title":"This shop has not granted orders:read","detail":"Send an access request for the scope."}}}}}},"429":{"description":"A rate limit was hit: see Retry-After and the RateLimit headers","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"RATE_LIMITED":{"summary":"RATE_LIMITED","value":{"type":"https://api.johku.com/problems/rate-limited","status":429,"code":"RATE_LIMITED","title":"Too many requests","detail":"Retry after 12 s."}}}}}},"503":{"description":"The endpoint is disabled or busy","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ENDPOINT_DISABLED":{"summary":"ENDPOINT_DISABLED","value":{"type":"https://api.johku.com/problems/endpoint-disabled","status":503,"code":"ENDPOINT_DISABLED","title":"This endpoint is temporarily disabled"}}}}}}}}},"/v1/shops/{shop}":{"get":{"operationId":"getShop","tags":["Catalog"],"summary":"A shop's public details: name, currency, languages, contacts","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_]{1,64}$","example":"johkula","description":"The shop id (its subdomain on johku.com)"},"required":true,"description":"The shop id (its subdomain on johku.com)","name":"shop","in":"path"},{"schema":{"type":"string","example":"fi-FI, en;q=0.8","description":"Picks the response language among the shop's locales; the shop default otherwise"},"required":false,"description":"Picks the response language among the shop's locales; the shop default otherwise","name":"Accept-Language","in":"header"}],"responses":{"200":{"description":"The shop","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Shop"}}}},"400":{"description":"The request is not valid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"VALIDATION_FAILED":{"summary":"VALIDATION_FAILED","value":{"type":"https://api.johku.com/problems/validation-failed","status":400,"code":"VALIDATION_FAILED","title":"The request is not valid","errors":[{"path":"limit","code":"TOO_BIG","message":"Too big: expected number to be <=100"}]}}}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"INVALID_KEY":{"summary":"INVALID_KEY","value":{"type":"https://api.johku.com/problems/invalid-key","status":401,"code":"INVALID_KEY","title":"The API key is not valid"}}}}}},"403":{"description":"The key, integration or shop connection does not allow this","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"SCOPE_NOT_GRANTED":{"summary":"SCOPE_NOT_GRANTED","value":{"type":"https://api.johku.com/problems/scope-not-granted","status":403,"code":"SCOPE_NOT_GRANTED","title":"This shop has not granted orders:read","detail":"Send an access request for the scope."}}}}}},"404":{"description":"No such shop","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"NOT_FOUND":{"summary":"NOT_FOUND","value":{"type":"https://api.johku.com/problems/not-found","status":404,"code":"NOT_FOUND","title":"Not found","detail":"No such shop"}}}}}},"429":{"description":"A rate limit was hit: see Retry-After and the RateLimit headers","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"RATE_LIMITED":{"summary":"RATE_LIMITED","value":{"type":"https://api.johku.com/problems/rate-limited","status":429,"code":"RATE_LIMITED","title":"Too many requests","detail":"Retry after 12 s."}}}}}},"502":{"description":"The shop backend did not answer as expected","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"BACKEND_ERROR":{"summary":"BACKEND_ERROR","value":{"type":"https://api.johku.com/problems/backend-error","status":502,"code":"BACKEND_ERROR","title":"The shop backend did not answer as expected","detail":"Try again in a moment."}}}}}},"503":{"description":"The endpoint is disabled or busy","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ENDPOINT_DISABLED":{"summary":"ENDPOINT_DISABLED","value":{"type":"https://api.johku.com/problems/endpoint-disabled","status":503,"code":"ENDPOINT_DISABLED","title":"This endpoint is temporarily disabled"}}}}}}}}},"/v1/shops/{shop}/categories":{"get":{"operationId":"listCategories","tags":["Catalog"],"summary":"The shop's storefront categories, in storefront order","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_]{1,64}$","example":"johkula","description":"The shop id (its subdomain on johku.com)"},"required":true,"description":"The shop id (its subdomain on johku.com)","name":"shop","in":"path"},{"schema":{"type":"string","example":"fi-FI, en;q=0.8","description":"Picks the response language among the shop's locales; the shop default otherwise"},"required":false,"description":"Picks the response language among the shop's locales; the shop default otherwise","name":"Accept-Language","in":"header"}],"responses":{"200":{"description":"The categories","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryList"}}}},"400":{"description":"The request is not valid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"VALIDATION_FAILED":{"summary":"VALIDATION_FAILED","value":{"type":"https://api.johku.com/problems/validation-failed","status":400,"code":"VALIDATION_FAILED","title":"The request is not valid","errors":[{"path":"limit","code":"TOO_BIG","message":"Too big: expected number to be <=100"}]}}}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"INVALID_KEY":{"summary":"INVALID_KEY","value":{"type":"https://api.johku.com/problems/invalid-key","status":401,"code":"INVALID_KEY","title":"The API key is not valid"}}}}}},"403":{"description":"The key, integration or shop connection does not allow this","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"SCOPE_NOT_GRANTED":{"summary":"SCOPE_NOT_GRANTED","value":{"type":"https://api.johku.com/problems/scope-not-granted","status":403,"code":"SCOPE_NOT_GRANTED","title":"This shop has not granted orders:read","detail":"Send an access request for the scope."}}}}}},"429":{"description":"A rate limit was hit: see Retry-After and the RateLimit headers","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"RATE_LIMITED":{"summary":"RATE_LIMITED","value":{"type":"https://api.johku.com/problems/rate-limited","status":429,"code":"RATE_LIMITED","title":"Too many requests","detail":"Retry after 12 s."}}}}}},"502":{"description":"The shop backend did not answer as expected","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"BACKEND_ERROR":{"summary":"BACKEND_ERROR","value":{"type":"https://api.johku.com/problems/backend-error","status":502,"code":"BACKEND_ERROR","title":"The shop backend did not answer as expected","detail":"Try again in a moment."}}}}}},"503":{"description":"The endpoint is disabled or busy","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ENDPOINT_DISABLED":{"summary":"ENDPOINT_DISABLED","value":{"type":"https://api.johku.com/problems/endpoint-disabled","status":503,"code":"ENDPOINT_DISABLED","title":"This endpoint is temporarily disabled"}}}}}}}}},"/v1/shops/{shop}/categories/{id}":{"get":{"operationId":"getCategory","tags":["Catalog"],"summary":"One category","description":"List its products with GET …/products?category={id}.","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_]{1,64}$","example":"johkula","description":"The shop id (its subdomain on johku.com)"},"required":true,"description":"The shop id (its subdomain on johku.com)","name":"shop","in":"path"},{"schema":{"type":"integer","exclusiveMinimum":0,"example":259},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","example":"fi-FI, en;q=0.8","description":"Picks the response language among the shop's locales; the shop default otherwise"},"required":false,"description":"Picks the response language among the shop's locales; the shop default otherwise","name":"Accept-Language","in":"header"}],"responses":{"200":{"description":"The category","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}},"400":{"description":"The request is not valid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"VALIDATION_FAILED":{"summary":"VALIDATION_FAILED","value":{"type":"https://api.johku.com/problems/validation-failed","status":400,"code":"VALIDATION_FAILED","title":"The request is not valid","errors":[{"path":"limit","code":"TOO_BIG","message":"Too big: expected number to be <=100"}]}}}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"INVALID_KEY":{"summary":"INVALID_KEY","value":{"type":"https://api.johku.com/problems/invalid-key","status":401,"code":"INVALID_KEY","title":"The API key is not valid"}}}}}},"403":{"description":"The key, integration or shop connection does not allow this","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"SCOPE_NOT_GRANTED":{"summary":"SCOPE_NOT_GRANTED","value":{"type":"https://api.johku.com/problems/scope-not-granted","status":403,"code":"SCOPE_NOT_GRANTED","title":"This shop has not granted orders:read","detail":"Send an access request for the scope."}}}}}},"404":{"description":"No such category","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"NOT_FOUND":{"summary":"NOT_FOUND","value":{"type":"https://api.johku.com/problems/not-found","status":404,"code":"NOT_FOUND","title":"Not found","detail":"No such category"}}}}}},"429":{"description":"A rate limit was hit: see Retry-After and the RateLimit headers","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"RATE_LIMITED":{"summary":"RATE_LIMITED","value":{"type":"https://api.johku.com/problems/rate-limited","status":429,"code":"RATE_LIMITED","title":"Too many requests","detail":"Retry after 12 s."}}}}}},"502":{"description":"The shop backend did not answer as expected","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"BACKEND_ERROR":{"summary":"BACKEND_ERROR","value":{"type":"https://api.johku.com/problems/backend-error","status":502,"code":"BACKEND_ERROR","title":"The shop backend did not answer as expected","detail":"Try again in a moment."}}}}}},"503":{"description":"The endpoint is disabled or busy","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ENDPOINT_DISABLED":{"summary":"ENDPOINT_DISABLED","value":{"type":"https://api.johku.com/problems/endpoint-disabled","status":503,"code":"ENDPOINT_DISABLED","title":"This endpoint is temporarily disabled"}}}}}}}}},"/v1/shops/{shop}/products":{"get":{"operationId":"listProducts","tags":["Catalog"],"summary":"Search or list the shop's published products","description":"Results come from the search index and can lag product edits by a little. A page can hold fewer items than `limit`; keep following `next_cursor` until it is null.","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_]{1,64}$","example":"johkula","description":"The shop id (its subdomain on johku.com)"},"required":true,"description":"The shop id (its subdomain on johku.com)","name":"shop","in":"path"},{"schema":{"type":"string","description":"The `next_cursor` of the previous page"},"required":false,"description":"The `next_cursor` of the previous page","name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","maxLength":200,"description":"Free text; leave out to list everything","example":"sauna"},"required":false,"description":"Free text; leave out to list everything","name":"q","in":"query"},{"schema":{"type":"integer","exclusiveMinimum":0,"description":"Only products in this category"},"required":false,"description":"Only products in this category","name":"category","in":"query"},{"schema":{"type":"string","example":"fi-FI, en;q=0.8","description":"Picks the response language among the shop's locales; the shop default otherwise"},"required":false,"description":"Picks the response language among the shop's locales; the shop default otherwise","name":"Accept-Language","in":"header"}],"responses":{"200":{"description":"A page of products","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductPage"}}}},"400":{"description":"The request is not valid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"VALIDATION_FAILED":{"summary":"VALIDATION_FAILED","value":{"type":"https://api.johku.com/problems/validation-failed","status":400,"code":"VALIDATION_FAILED","title":"The request is not valid","errors":[{"path":"limit","code":"TOO_BIG","message":"Too big: expected number to be <=100"}]}}}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"INVALID_KEY":{"summary":"INVALID_KEY","value":{"type":"https://api.johku.com/problems/invalid-key","status":401,"code":"INVALID_KEY","title":"The API key is not valid"}}}}}},"403":{"description":"The key, integration or shop connection does not allow this","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"SCOPE_NOT_GRANTED":{"summary":"SCOPE_NOT_GRANTED","value":{"type":"https://api.johku.com/problems/scope-not-granted","status":403,"code":"SCOPE_NOT_GRANTED","title":"This shop has not granted orders:read","detail":"Send an access request for the scope."}}}}}},"429":{"description":"A rate limit was hit: see Retry-After and the RateLimit headers","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"RATE_LIMITED":{"summary":"RATE_LIMITED","value":{"type":"https://api.johku.com/problems/rate-limited","status":429,"code":"RATE_LIMITED","title":"Too many requests","detail":"Retry after 12 s."}}}}}},"502":{"description":"The shop backend did not answer as expected","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"BACKEND_ERROR":{"summary":"BACKEND_ERROR","value":{"type":"https://api.johku.com/problems/backend-error","status":502,"code":"BACKEND_ERROR","title":"The shop backend did not answer as expected","detail":"Try again in a moment."}}}}}},"503":{"description":"The endpoint is disabled or busy","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ENDPOINT_DISABLED":{"summary":"ENDPOINT_DISABLED","value":{"type":"https://api.johku.com/problems/endpoint-disabled","status":503,"code":"ENDPOINT_DISABLED","title":"This endpoint is temporarily disabled"}}}}}}}}},"/v1/shops/{shop}/products/{id}":{"get":{"operationId":"getProduct","tags":["Catalog"],"summary":"One product","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_]{1,64}$","example":"johkula","description":"The shop id (its subdomain on johku.com)"},"required":true,"description":"The shop id (its subdomain on johku.com)","name":"shop","in":"path"},{"schema":{"type":"integer","exclusiveMinimum":0,"example":259},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","example":"fi-FI, en;q=0.8","description":"Picks the response language among the shop's locales; the shop default otherwise"},"required":false,"description":"Picks the response language among the shop's locales; the shop default otherwise","name":"Accept-Language","in":"header"}],"responses":{"200":{"description":"The product","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"400":{"description":"The request is not valid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"VALIDATION_FAILED":{"summary":"VALIDATION_FAILED","value":{"type":"https://api.johku.com/problems/validation-failed","status":400,"code":"VALIDATION_FAILED","title":"The request is not valid","errors":[{"path":"limit","code":"TOO_BIG","message":"Too big: expected number to be <=100"}]}}}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"INVALID_KEY":{"summary":"INVALID_KEY","value":{"type":"https://api.johku.com/problems/invalid-key","status":401,"code":"INVALID_KEY","title":"The API key is not valid"}}}}}},"403":{"description":"The key, integration or shop connection does not allow this","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"SCOPE_NOT_GRANTED":{"summary":"SCOPE_NOT_GRANTED","value":{"type":"https://api.johku.com/problems/scope-not-granted","status":403,"code":"SCOPE_NOT_GRANTED","title":"This shop has not granted orders:read","detail":"Send an access request for the scope."}}}}}},"404":{"description":"No such product, or not published","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"NOT_FOUND":{"summary":"NOT_FOUND","value":{"type":"https://api.johku.com/problems/not-found","status":404,"code":"NOT_FOUND","title":"Not found","detail":"No such product, or not published"}}}}}},"429":{"description":"A rate limit was hit: see Retry-After and the RateLimit headers","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"RATE_LIMITED":{"summary":"RATE_LIMITED","value":{"type":"https://api.johku.com/problems/rate-limited","status":429,"code":"RATE_LIMITED","title":"Too many requests","detail":"Retry after 12 s."}}}}}},"502":{"description":"The shop backend did not answer as expected","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"BACKEND_ERROR":{"summary":"BACKEND_ERROR","value":{"type":"https://api.johku.com/problems/backend-error","status":502,"code":"BACKEND_ERROR","title":"The shop backend did not answer as expected","detail":"Try again in a moment."}}}}}},"503":{"description":"The endpoint is disabled or busy","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ENDPOINT_DISABLED":{"summary":"ENDPOINT_DISABLED","value":{"type":"https://api.johku.com/problems/endpoint-disabled","status":503,"code":"ENDPOINT_DISABLED","title":"This endpoint is temporarily disabled"}}}}}}}}},"/v1/shops/{shop}/products/{id}/booking-options":{"get":{"operationId":"getBookingOptions","tags":["Booking"],"summary":"What can be chosen when booking a product","description":"Self-describing: `modes` and `hints` say which booking line fields to give. Add date, participants and the other filters to see that day's times, shows, departures or check-in. Products with `bookable_via_api: false` are booked through `booking_url`.","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_]{1,64}$","example":"johkula","description":"The shop id (its subdomain on johku.com)"},"required":true,"description":"The shop id (its subdomain on johku.com)","name":"shop","in":"path"},{"schema":{"type":"integer","exclusiveMinimum":0,"example":259},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-24","description":"With a date, the response lists that day's times, shows, departures or check-in"},"required":false,"description":"With a date, the response lists that day's times, shows, departures or check-in","name":"date","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-24"},"required":false,"name":"end_date","in":"query"},{"schema":{"type":"string","pattern":"^\\d{2}:\\d{2}$","example":"14:30","description":"Adds free places per pool choice and the pick-up places for that start"},"required":false,"description":"Adds free places per pool choice and the pick-up places for that start","name":"start_time","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":500},"required":false,"name":"participants","in":"query"},{"schema":{"type":"integer","exclusiveMinimum":0,"description":"Transport: departure stop id from `routes`"},"required":false,"description":"Transport: departure stop id from `routes`","name":"origin","in":"query"},{"schema":{"type":"integer","exclusiveMinimum":0},"required":false,"name":"destination","in":"query"},{"schema":{"type":"string","example":"fi-FI, en;q=0.8","description":"Picks the response language among the shop's locales; the shop default otherwise"},"required":false,"description":"Picks the response language among the shop's locales; the shop default otherwise","name":"Accept-Language","in":"header"}],"responses":{"200":{"description":"The booking options","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookingOptions"}}}},"400":{"description":"The request is not valid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"VALIDATION_FAILED":{"summary":"VALIDATION_FAILED","value":{"type":"https://api.johku.com/problems/validation-failed","status":400,"code":"VALIDATION_FAILED","title":"The request is not valid","errors":[{"path":"limit","code":"TOO_BIG","message":"Too big: expected number to be <=100"}]}}}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"INVALID_KEY":{"summary":"INVALID_KEY","value":{"type":"https://api.johku.com/problems/invalid-key","status":401,"code":"INVALID_KEY","title":"The API key is not valid"}}}}}},"403":{"description":"The key, integration or shop connection does not allow this","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"SCOPE_NOT_GRANTED":{"summary":"SCOPE_NOT_GRANTED","value":{"type":"https://api.johku.com/problems/scope-not-granted","status":403,"code":"SCOPE_NOT_GRANTED","title":"This shop has not granted orders:read","detail":"Send an access request for the scope."}}}}}},"404":{"description":"No such product, or not published","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"NOT_FOUND":{"summary":"NOT_FOUND","value":{"type":"https://api.johku.com/problems/not-found","status":404,"code":"NOT_FOUND","title":"Not found","detail":"No such product, or not published"}}}}}},"422":{"description":"A line can't be booked as given: `code` is the booking engine's, `errors[].line` the line. `PRODUCT_NOT_FOUND`: no such published product; `PRODUCT_NOT_BOOKABLE_VIA_API`: book it through its `booking_url`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"RESERVATION_INSUFFICIENT_CAPACITY":{"summary":"RESERVATION_INSUFFICIENT_CAPACITY","value":{"type":"https://api.johku.com/problems/reservation-insufficient-capacity","status":422,"code":"RESERVATION_INSUFFICIENT_CAPACITY","title":"The booking can't be made as given","detail":"Line 1: Canoe tour is not available at the selected time.","errors":[{"line":0,"code":"RESERVATION_INSUFFICIENT_CAPACITY","message":"Canoe tour is not available at the selected time."}]}},"PRODUCT_NOT_FOUND":{"summary":"PRODUCT_NOT_FOUND","value":{"type":"https://api.johku.com/problems/product-not-found","title":"The booking can't be made as given","status":422,"code":"PRODUCT_NOT_FOUND","detail":"No published product 259.","errors":[{"line":0,"code":"PRODUCT_NOT_FOUND","message":"No published product 259"}]}},"PRODUCT_NOT_BOOKABLE_VIA_API":{"summary":"PRODUCT_NOT_BOOKABLE_VIA_API","value":{"type":"https://api.johku.com/problems/product-not-bookable-via-api","title":"The booking can't be made as given","status":422,"code":"PRODUCT_NOT_BOOKABLE_VIA_API","detail":"Line 1: Season pass (259) can't be booked through the API. Send the customer to the product's booking_url instead.","errors":[{"line":0,"code":"PRODUCT_NOT_BOOKABLE_VIA_API","message":"Season pass (259) can't be booked through the API."}]}}}}}},"429":{"description":"A rate limit was hit: see Retry-After and the RateLimit headers","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"RATE_LIMITED":{"summary":"RATE_LIMITED","value":{"type":"https://api.johku.com/problems/rate-limited","status":429,"code":"RATE_LIMITED","title":"Too many requests","detail":"Retry after 12 s."}}}}}},"502":{"description":"The shop backend did not answer as expected","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"BACKEND_ERROR":{"summary":"BACKEND_ERROR","value":{"type":"https://api.johku.com/problems/backend-error","status":502,"code":"BACKEND_ERROR","title":"The shop backend did not answer as expected","detail":"Try again in a moment."}}}}}},"503":{"description":"The endpoint is disabled or busy","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ENDPOINT_DISABLED":{"summary":"ENDPOINT_DISABLED","value":{"type":"https://api.johku.com/problems/endpoint-disabled","status":503,"code":"ENDPOINT_DISABLED","title":"This endpoint is temporarily disabled"}}}}}}}}},"/v1/shops/{shop}/products/{id}/availability":{"get":{"operationId":"getAvailability","tags":["Booking"],"summary":"The days something can start, over a date range","description":"For products booked by the day or by the hour. Events list their shows in booking-options instead.","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_]{1,64}$","example":"johkula","description":"The shop id (its subdomain on johku.com)"},"required":true,"description":"The shop id (its subdomain on johku.com)","name":"shop","in":"path"},{"schema":{"type":"integer","exclusiveMinimum":0,"example":259},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-24"},"required":true,"name":"from","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-24","description":"At most 93 days after `from`"},"required":true,"description":"At most 93 days after `from`","name":"to","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":500,"default":1},"required":false,"name":"participants","in":"query"}],"responses":{"200":{"description":"Free dates","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Availability"}}}},"400":{"description":"The request is not valid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"VALIDATION_FAILED":{"summary":"VALIDATION_FAILED","value":{"type":"https://api.johku.com/problems/validation-failed","status":400,"code":"VALIDATION_FAILED","title":"The request is not valid","errors":[{"path":"limit","code":"TOO_BIG","message":"Too big: expected number to be <=100"}]}}}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"INVALID_KEY":{"summary":"INVALID_KEY","value":{"type":"https://api.johku.com/problems/invalid-key","status":401,"code":"INVALID_KEY","title":"The API key is not valid"}}}}}},"403":{"description":"The key, integration or shop connection does not allow this","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"SCOPE_NOT_GRANTED":{"summary":"SCOPE_NOT_GRANTED","value":{"type":"https://api.johku.com/problems/scope-not-granted","status":403,"code":"SCOPE_NOT_GRANTED","title":"This shop has not granted orders:read","detail":"Send an access request for the scope."}}}}}},"404":{"description":"No such product","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"NOT_FOUND":{"summary":"NOT_FOUND","value":{"type":"https://api.johku.com/problems/not-found","status":404,"code":"NOT_FOUND","title":"Not found","detail":"No such product"}}}}}},"422":{"description":"A line can't be booked as given: `code` is the booking engine's, `errors[].line` the line. `PRODUCT_NOT_FOUND`: no such published product; `PRODUCT_NOT_BOOKABLE_VIA_API`: book it through its `booking_url`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"RESERVATION_INSUFFICIENT_CAPACITY":{"summary":"RESERVATION_INSUFFICIENT_CAPACITY","value":{"type":"https://api.johku.com/problems/reservation-insufficient-capacity","status":422,"code":"RESERVATION_INSUFFICIENT_CAPACITY","title":"The booking can't be made as given","detail":"Line 1: Canoe tour is not available at the selected time.","errors":[{"line":0,"code":"RESERVATION_INSUFFICIENT_CAPACITY","message":"Canoe tour is not available at the selected time."}]}},"PRODUCT_NOT_FOUND":{"summary":"PRODUCT_NOT_FOUND","value":{"type":"https://api.johku.com/problems/product-not-found","title":"The booking can't be made as given","status":422,"code":"PRODUCT_NOT_FOUND","detail":"No published product 259.","errors":[{"line":0,"code":"PRODUCT_NOT_FOUND","message":"No published product 259"}]}},"PRODUCT_NOT_BOOKABLE_VIA_API":{"summary":"PRODUCT_NOT_BOOKABLE_VIA_API","value":{"type":"https://api.johku.com/problems/product-not-bookable-via-api","title":"The booking can't be made as given","status":422,"code":"PRODUCT_NOT_BOOKABLE_VIA_API","detail":"Line 1: Season pass (259) can't be booked through the API. Send the customer to the product's booking_url instead.","errors":[{"line":0,"code":"PRODUCT_NOT_BOOKABLE_VIA_API","message":"Season pass (259) can't be booked through the API."}]}}}}}},"429":{"description":"A rate limit was hit: see Retry-After and the RateLimit headers","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"RATE_LIMITED":{"summary":"RATE_LIMITED","value":{"type":"https://api.johku.com/problems/rate-limited","status":429,"code":"RATE_LIMITED","title":"Too many requests","detail":"Retry after 12 s."}}}}}},"502":{"description":"The shop backend did not answer as expected","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"BACKEND_ERROR":{"summary":"BACKEND_ERROR","value":{"type":"https://api.johku.com/problems/backend-error","status":502,"code":"BACKEND_ERROR","title":"The shop backend did not answer as expected","detail":"Try again in a moment."}}}}}},"503":{"description":"The endpoint is disabled or busy","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ENDPOINT_DISABLED":{"summary":"ENDPOINT_DISABLED","value":{"type":"https://api.johku.com/problems/endpoint-disabled","status":503,"code":"ENDPOINT_DISABLED","title":"This endpoint is temporarily disabled"}}}}}}}}},"/v1/shops/{shop}/shows/{id}/seatmap":{"get":{"operationId":"getSeatmap","tags":["Booking"],"summary":"The seats of a show, with what is free","description":"For events whose venue has a seat map: pick seats here and send their ids in the line's `seat_ids`. A show sold from a seat map needs them (booking options say so). The answer is live, never cached.","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_]{1,64}$","example":"johkula","description":"The shop id (its subdomain on johku.com)"},"required":true,"description":"The shop id (its subdomain on johku.com)","name":"shop","in":"path"},{"schema":{"type":"integer","exclusiveMinimum":0,"example":259},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","example":"fi-FI, en;q=0.8","description":"Picks the response language among the shop's locales; the shop default otherwise"},"required":false,"description":"Picks the response language among the shop's locales; the shop default otherwise","name":"Accept-Language","in":"header"}],"responses":{"200":{"description":"The seat map","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seatmap"}}}},"400":{"description":"The request is not valid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"VALIDATION_FAILED":{"summary":"VALIDATION_FAILED","value":{"type":"https://api.johku.com/problems/validation-failed","status":400,"code":"VALIDATION_FAILED","title":"The request is not valid","errors":[{"path":"limit","code":"TOO_BIG","message":"Too big: expected number to be <=100"}]}}}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"INVALID_KEY":{"summary":"INVALID_KEY","value":{"type":"https://api.johku.com/problems/invalid-key","status":401,"code":"INVALID_KEY","title":"The API key is not valid"}}}}}},"403":{"description":"The key, integration or shop connection does not allow this","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"SCOPE_NOT_GRANTED":{"summary":"SCOPE_NOT_GRANTED","value":{"type":"https://api.johku.com/problems/scope-not-granted","status":403,"code":"SCOPE_NOT_GRANTED","title":"This shop has not granted orders:read","detail":"Send an access request for the scope."}}}}}},"404":{"description":"No such show, or its venue has no seat map","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"NOT_FOUND":{"summary":"NOT_FOUND","value":{"type":"https://api.johku.com/problems/not-found","status":404,"code":"NOT_FOUND","title":"Not found","detail":"No such show, or its venue has no seat map"}}}}}},"429":{"description":"A rate limit was hit: see Retry-After and the RateLimit headers","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"RATE_LIMITED":{"summary":"RATE_LIMITED","value":{"type":"https://api.johku.com/problems/rate-limited","status":429,"code":"RATE_LIMITED","title":"Too many requests","detail":"Retry after 12 s."}}}}}},"502":{"description":"The shop backend did not answer as expected","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"BACKEND_ERROR":{"summary":"BACKEND_ERROR","value":{"type":"https://api.johku.com/problems/backend-error","status":502,"code":"BACKEND_ERROR","title":"The shop backend did not answer as expected","detail":"Try again in a moment."}}}}}},"503":{"description":"The endpoint is disabled or busy","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ENDPOINT_DISABLED":{"summary":"ENDPOINT_DISABLED","value":{"type":"https://api.johku.com/problems/endpoint-disabled","status":503,"code":"ENDPOINT_DISABLED","title":"This endpoint is temporarily disabled"}}}}}}}}},"/v1/shops/{shop}/quotes":{"post":{"operationId":"createQuote","tags":["Booking"],"summary":"Price booking lines without holding anything","description":"Runs the same checks as a cart: availability, deadlines, price rules, seats, options and forms.","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_]{1,64}$","example":"johkula","description":"The shop id (its subdomain on johku.com)"},"required":true,"description":"The shop id (its subdomain on johku.com)","name":"shop","in":"path"},{"schema":{"type":"string","example":"fi-FI, en;q=0.8","description":"Picks the response language among the shop's locales; the shop default otherwise"},"required":false,"description":"Picks the response language among the shop's locales; the shop default otherwise","name":"Accept-Language","in":"header"},{"schema":{"type":"string","minLength":8,"maxLength":128,"example":"0b9f6c1e-3d0a-4c35-9b8e-2f3f1d6b7a10","description":"Retrying a POST with the same key within 24 hours returns the first result instead of acting twice"},"required":false,"description":"Retrying a POST with the same key within 24 hours returns the first result instead of acting twice","name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteRequest"}}}},"responses":{"200":{"description":"The priced lines","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Quote"}}}},"400":{"description":"The request is not valid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"VALIDATION_FAILED":{"summary":"VALIDATION_FAILED","value":{"type":"https://api.johku.com/problems/validation-failed","status":400,"code":"VALIDATION_FAILED","title":"The request is not valid","errors":[{"path":"limit","code":"TOO_BIG","message":"Too big: expected number to be <=100"}]}}}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"INVALID_KEY":{"summary":"INVALID_KEY","value":{"type":"https://api.johku.com/problems/invalid-key","status":401,"code":"INVALID_KEY","title":"The API key is not valid"}}}}}},"403":{"description":"The key, integration or shop connection does not allow this","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"SCOPE_NOT_GRANTED":{"summary":"SCOPE_NOT_GRANTED","value":{"type":"https://api.johku.com/problems/scope-not-granted","status":403,"code":"SCOPE_NOT_GRANTED","title":"This shop has not granted orders:read","detail":"Send an access request for the scope."}}}}}},"409":{"description":"`IDEMPOTENCY_IN_PROGRESS`: a request with this Idempotency-Key is still running; retry after `Retry-After`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"IDEMPOTENCY_IN_PROGRESS":{"summary":"IDEMPOTENCY_IN_PROGRESS","value":{"type":"https://api.johku.com/problems/idempotency-in-progress","title":"A request with this Idempotency-Key is still running","status":409,"code":"IDEMPOTENCY_IN_PROGRESS","detail":"Retry in a moment to get its result."}}}}}},"422":{"description":"A line can't be booked as given: `code` is the booking engine's, `errors[].line` the line. `PRODUCT_NOT_FOUND`: no such published product; `PRODUCT_NOT_BOOKABLE_VIA_API`: book it through its `booking_url`. Or `IDEMPOTENCY_KEY_REUSED`: this Idempotency-Key was used for a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"RESERVATION_INSUFFICIENT_CAPACITY":{"summary":"RESERVATION_INSUFFICIENT_CAPACITY","value":{"type":"https://api.johku.com/problems/reservation-insufficient-capacity","status":422,"code":"RESERVATION_INSUFFICIENT_CAPACITY","title":"The booking can't be made as given","detail":"Line 1: Canoe tour is not available at the selected time.","errors":[{"line":0,"code":"RESERVATION_INSUFFICIENT_CAPACITY","message":"Canoe tour is not available at the selected time."}]}},"PRODUCT_NOT_FOUND":{"summary":"PRODUCT_NOT_FOUND","value":{"type":"https://api.johku.com/problems/product-not-found","title":"The booking can't be made as given","status":422,"code":"PRODUCT_NOT_FOUND","detail":"No published product 259.","errors":[{"line":0,"code":"PRODUCT_NOT_FOUND","message":"No published product 259"}]}},"PRODUCT_NOT_BOOKABLE_VIA_API":{"summary":"PRODUCT_NOT_BOOKABLE_VIA_API","value":{"type":"https://api.johku.com/problems/product-not-bookable-via-api","title":"The booking can't be made as given","status":422,"code":"PRODUCT_NOT_BOOKABLE_VIA_API","detail":"Line 1: Season pass (259) can't be booked through the API. Send the customer to the product's booking_url instead.","errors":[{"line":0,"code":"PRODUCT_NOT_BOOKABLE_VIA_API","message":"Season pass (259) can't be booked through the API."}]}},"IDEMPOTENCY_KEY_REUSED":{"summary":"IDEMPOTENCY_KEY_REUSED","value":{"type":"https://api.johku.com/problems/idempotency-key-reused","title":"This Idempotency-Key was used for a different request","status":422,"code":"IDEMPOTENCY_KEY_REUSED","detail":"Use a new key for a new request."}}}}}},"429":{"description":"A rate limit was hit: see Retry-After and the RateLimit headers","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"RATE_LIMITED":{"summary":"RATE_LIMITED","value":{"type":"https://api.johku.com/problems/rate-limited","status":429,"code":"RATE_LIMITED","title":"Too many requests","detail":"Retry after 12 s."}}}}}},"502":{"description":"The shop backend did not answer as expected","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"BACKEND_ERROR":{"summary":"BACKEND_ERROR","value":{"type":"https://api.johku.com/problems/backend-error","status":502,"code":"BACKEND_ERROR","title":"The shop backend did not answer as expected","detail":"Try again in a moment."}}}}}},"503":{"description":"The endpoint is disabled or busy","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ENDPOINT_DISABLED":{"summary":"ENDPOINT_DISABLED","value":{"type":"https://api.johku.com/problems/endpoint-disabled","status":503,"code":"ENDPOINT_DISABLED","title":"This endpoint is temporarily disabled"}}}}}}}}},"/v1/shops/{shop}/carts":{"post":{"operationId":"createCart","tags":["Carts"],"summary":"Hold booking lines in a new cart","description":"The places are held for 30 minutes. Send the customer to checkout with POST …/carts/{id}/checkout. Carts are kept for 2 hours.","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_]{1,64}$","example":"johkula","description":"The shop id (its subdomain on johku.com)"},"required":true,"description":"The shop id (its subdomain on johku.com)","name":"shop","in":"path"},{"schema":{"type":"string","example":"fi-FI, en;q=0.8","description":"Picks the response language among the shop's locales; the shop default otherwise"},"required":false,"description":"Picks the response language among the shop's locales; the shop default otherwise","name":"Accept-Language","in":"header"},{"schema":{"type":"string","minLength":8,"maxLength":128,"example":"0b9f6c1e-3d0a-4c35-9b8e-2f3f1d6b7a10","description":"Retrying a POST with the same key within 24 hours returns the first result instead of acting twice"},"required":false,"description":"Retrying a POST with the same key within 24 hours returns the first result instead of acting twice","name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CartRequest"}}}},"responses":{"201":{"description":"The cart","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Cart"}}}},"400":{"description":"The request is not valid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"VALIDATION_FAILED":{"summary":"VALIDATION_FAILED","value":{"type":"https://api.johku.com/problems/validation-failed","status":400,"code":"VALIDATION_FAILED","title":"The request is not valid","errors":[{"path":"limit","code":"TOO_BIG","message":"Too big: expected number to be <=100"}]}}}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"INVALID_KEY":{"summary":"INVALID_KEY","value":{"type":"https://api.johku.com/problems/invalid-key","status":401,"code":"INVALID_KEY","title":"The API key is not valid"}}}}}},"403":{"description":"The key, integration or shop connection does not allow this","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"SCOPE_NOT_GRANTED":{"summary":"SCOPE_NOT_GRANTED","value":{"type":"https://api.johku.com/problems/scope-not-granted","status":403,"code":"SCOPE_NOT_GRANTED","title":"This shop has not granted orders:read","detail":"Send an access request for the scope."}}}}}},"409":{"description":"`IDEMPOTENCY_IN_PROGRESS`: a request with this Idempotency-Key is still running; retry after `Retry-After`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"IDEMPOTENCY_IN_PROGRESS":{"summary":"IDEMPOTENCY_IN_PROGRESS","value":{"type":"https://api.johku.com/problems/idempotency-in-progress","title":"A request with this Idempotency-Key is still running","status":409,"code":"IDEMPOTENCY_IN_PROGRESS","detail":"Retry in a moment to get its result."}}}}}},"422":{"description":"A line can't be booked as given: `code` is the booking engine's, `errors[].line` the line. `PRODUCT_NOT_FOUND`: no such published product; `PRODUCT_NOT_BOOKABLE_VIA_API`: book it through its `booking_url`. Or `IDEMPOTENCY_KEY_REUSED`: this Idempotency-Key was used for a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"RESERVATION_INSUFFICIENT_CAPACITY":{"summary":"RESERVATION_INSUFFICIENT_CAPACITY","value":{"type":"https://api.johku.com/problems/reservation-insufficient-capacity","status":422,"code":"RESERVATION_INSUFFICIENT_CAPACITY","title":"The booking can't be made as given","detail":"Line 1: Canoe tour is not available at the selected time.","errors":[{"line":0,"code":"RESERVATION_INSUFFICIENT_CAPACITY","message":"Canoe tour is not available at the selected time."}]}},"PRODUCT_NOT_FOUND":{"summary":"PRODUCT_NOT_FOUND","value":{"type":"https://api.johku.com/problems/product-not-found","title":"The booking can't be made as given","status":422,"code":"PRODUCT_NOT_FOUND","detail":"No published product 259.","errors":[{"line":0,"code":"PRODUCT_NOT_FOUND","message":"No published product 259"}]}},"PRODUCT_NOT_BOOKABLE_VIA_API":{"summary":"PRODUCT_NOT_BOOKABLE_VIA_API","value":{"type":"https://api.johku.com/problems/product-not-bookable-via-api","title":"The booking can't be made as given","status":422,"code":"PRODUCT_NOT_BOOKABLE_VIA_API","detail":"Line 1: Season pass (259) can't be booked through the API. Send the customer to the product's booking_url instead.","errors":[{"line":0,"code":"PRODUCT_NOT_BOOKABLE_VIA_API","message":"Season pass (259) can't be booked through the API."}]}},"IDEMPOTENCY_KEY_REUSED":{"summary":"IDEMPOTENCY_KEY_REUSED","value":{"type":"https://api.johku.com/problems/idempotency-key-reused","title":"This Idempotency-Key was used for a different request","status":422,"code":"IDEMPOTENCY_KEY_REUSED","detail":"Use a new key for a new request."}}}}}},"429":{"description":"A rate limit was hit: see Retry-After and the RateLimit headers","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"RATE_LIMITED":{"summary":"RATE_LIMITED","value":{"type":"https://api.johku.com/problems/rate-limited","status":429,"code":"RATE_LIMITED","title":"Too many requests","detail":"Retry after 12 s."}}}}}},"502":{"description":"The shop backend did not answer as expected","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"BACKEND_ERROR":{"summary":"BACKEND_ERROR","value":{"type":"https://api.johku.com/problems/backend-error","status":502,"code":"BACKEND_ERROR","title":"The shop backend did not answer as expected","detail":"Try again in a moment."}}}}}},"503":{"description":"The endpoint is disabled or busy","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ENDPOINT_DISABLED":{"summary":"ENDPOINT_DISABLED","value":{"type":"https://api.johku.com/problems/endpoint-disabled","status":503,"code":"ENDPOINT_DISABLED","title":"This endpoint is temporarily disabled"}}}}}}}}},"/v1/shops/{shop}/carts/{id}":{"get":{"operationId":"getCart","tags":["Carts"],"summary":"A cart","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_]{1,64}$","example":"johkula","description":"The shop id (its subdomain on johku.com)"},"required":true,"description":"The shop id (its subdomain on johku.com)","name":"shop","in":"path"},{"schema":{"type":"string","pattern":"^crt_[A-Za-z0-9]{16,40}$","example":"crt_8f3k2m9q1x7v4b6n"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","example":"fi-FI, en;q=0.8","description":"Picks the response language among the shop's locales; the shop default otherwise"},"required":false,"description":"Picks the response language among the shop's locales; the shop default otherwise","name":"Accept-Language","in":"header"}],"responses":{"200":{"description":"The cart","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Cart"}}}},"400":{"description":"The request is not valid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"VALIDATION_FAILED":{"summary":"VALIDATION_FAILED","value":{"type":"https://api.johku.com/problems/validation-failed","status":400,"code":"VALIDATION_FAILED","title":"The request is not valid","errors":[{"path":"limit","code":"TOO_BIG","message":"Too big: expected number to be <=100"}]}}}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"INVALID_KEY":{"summary":"INVALID_KEY","value":{"type":"https://api.johku.com/problems/invalid-key","status":401,"code":"INVALID_KEY","title":"The API key is not valid"}}}}}},"403":{"description":"The key, integration or shop connection does not allow this","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"SCOPE_NOT_GRANTED":{"summary":"SCOPE_NOT_GRANTED","value":{"type":"https://api.johku.com/problems/scope-not-granted","status":403,"code":"SCOPE_NOT_GRANTED","title":"This shop has not granted orders:read","detail":"Send an access request for the scope."}}}}}},"404":{"description":"No such cart","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"NOT_FOUND":{"summary":"NOT_FOUND","value":{"type":"https://api.johku.com/problems/not-found","status":404,"code":"NOT_FOUND","title":"Not found","detail":"No such cart"}}}}}},"429":{"description":"A rate limit was hit: see Retry-After and the RateLimit headers","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"RATE_LIMITED":{"summary":"RATE_LIMITED","value":{"type":"https://api.johku.com/problems/rate-limited","status":429,"code":"RATE_LIMITED","title":"Too many requests","detail":"Retry after 12 s."}}}}}},"502":{"description":"The shop backend did not answer as expected","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"BACKEND_ERROR":{"summary":"BACKEND_ERROR","value":{"type":"https://api.johku.com/problems/backend-error","status":502,"code":"BACKEND_ERROR","title":"The shop backend did not answer as expected","detail":"Try again in a moment."}}}}}},"503":{"description":"The endpoint is disabled or busy","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ENDPOINT_DISABLED":{"summary":"ENDPOINT_DISABLED","value":{"type":"https://api.johku.com/problems/endpoint-disabled","status":503,"code":"ENDPOINT_DISABLED","title":"This endpoint is temporarily disabled"}}}}}}}},"put":{"operationId":"replaceCart","tags":["Carts"],"summary":"Replace a cart's lines","description":"The new lines may overlap the old ones (a shorter time, one more participant): the cart's own places count as free. If the new lines can't be held, the answer is 422 and the cart keeps its old lines, held again with a new `hold_until`. Only an `active` cart can be changed: once the customer is in the shop's checkout, the cart is theirs.","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_]{1,64}$","example":"johkula","description":"The shop id (its subdomain on johku.com)"},"required":true,"description":"The shop id (its subdomain on johku.com)","name":"shop","in":"path"},{"schema":{"type":"string","pattern":"^crt_[A-Za-z0-9]{16,40}$","example":"crt_8f3k2m9q1x7v4b6n"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","example":"fi-FI, en;q=0.8","description":"Picks the response language among the shop's locales; the shop default otherwise"},"required":false,"description":"Picks the response language among the shop's locales; the shop default otherwise","name":"Accept-Language","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CartRequest"}}}},"responses":{"200":{"description":"The cart","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Cart"}}}},"400":{"description":"The request is not valid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"VALIDATION_FAILED":{"summary":"VALIDATION_FAILED","value":{"type":"https://api.johku.com/problems/validation-failed","status":400,"code":"VALIDATION_FAILED","title":"The request is not valid","errors":[{"path":"limit","code":"TOO_BIG","message":"Too big: expected number to be <=100"}]}}}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"INVALID_KEY":{"summary":"INVALID_KEY","value":{"type":"https://api.johku.com/problems/invalid-key","status":401,"code":"INVALID_KEY","title":"The API key is not valid"}}}}}},"403":{"description":"The key, integration or shop connection does not allow this","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"SCOPE_NOT_GRANTED":{"summary":"SCOPE_NOT_GRANTED","value":{"type":"https://api.johku.com/problems/scope-not-granted","status":403,"code":"SCOPE_NOT_GRANTED","title":"This shop has not granted orders:read","detail":"Send an access request for the scope."}}}}}},"404":{"description":"No such cart","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"NOT_FOUND":{"summary":"NOT_FOUND","value":{"type":"https://api.johku.com/problems/not-found","status":404,"code":"NOT_FOUND","title":"Not found","detail":"No such cart"}}}}}},"409":{"description":"`CART_NOT_ON_HOLD`: the cart is in the shop's checkout, ordered, released or expired","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"CART_NOT_ON_HOLD":{"summary":"CART_NOT_ON_HOLD","value":{"type":"https://api.johku.com/problems/cart-not-on-hold","title":"The cart is no longer on hold","status":409,"code":"CART_NOT_ON_HOLD"}}}}}},"422":{"description":"A line can't be booked as given: `code` is the booking engine's, `errors[].line` the line. `PRODUCT_NOT_FOUND`: no such published product; `PRODUCT_NOT_BOOKABLE_VIA_API`: book it through its `booking_url`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"RESERVATION_INSUFFICIENT_CAPACITY":{"summary":"RESERVATION_INSUFFICIENT_CAPACITY","value":{"type":"https://api.johku.com/problems/reservation-insufficient-capacity","status":422,"code":"RESERVATION_INSUFFICIENT_CAPACITY","title":"The booking can't be made as given","detail":"Line 1: Canoe tour is not available at the selected time.","errors":[{"line":0,"code":"RESERVATION_INSUFFICIENT_CAPACITY","message":"Canoe tour is not available at the selected time."}]}},"PRODUCT_NOT_FOUND":{"summary":"PRODUCT_NOT_FOUND","value":{"type":"https://api.johku.com/problems/product-not-found","title":"The booking can't be made as given","status":422,"code":"PRODUCT_NOT_FOUND","detail":"No published product 259.","errors":[{"line":0,"code":"PRODUCT_NOT_FOUND","message":"No published product 259"}]}},"PRODUCT_NOT_BOOKABLE_VIA_API":{"summary":"PRODUCT_NOT_BOOKABLE_VIA_API","value":{"type":"https://api.johku.com/problems/product-not-bookable-via-api","title":"The booking can't be made as given","status":422,"code":"PRODUCT_NOT_BOOKABLE_VIA_API","detail":"Line 1: Season pass (259) can't be booked through the API. Send the customer to the product's booking_url instead.","errors":[{"line":0,"code":"PRODUCT_NOT_BOOKABLE_VIA_API","message":"Season pass (259) can't be booked through the API."}]}}}}}},"429":{"description":"A rate limit was hit: see Retry-After and the RateLimit headers","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"RATE_LIMITED":{"summary":"RATE_LIMITED","value":{"type":"https://api.johku.com/problems/rate-limited","status":429,"code":"RATE_LIMITED","title":"Too many requests","detail":"Retry after 12 s."}}}}}},"502":{"description":"The shop backend did not answer as expected","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"BACKEND_ERROR":{"summary":"BACKEND_ERROR","value":{"type":"https://api.johku.com/problems/backend-error","status":502,"code":"BACKEND_ERROR","title":"The shop backend did not answer as expected","detail":"Try again in a moment."}}}}}},"503":{"description":"The endpoint is disabled or busy","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ENDPOINT_DISABLED":{"summary":"ENDPOINT_DISABLED","value":{"type":"https://api.johku.com/problems/endpoint-disabled","status":503,"code":"ENDPOINT_DISABLED","title":"This endpoint is temporarily disabled"}}}}}}}},"delete":{"operationId":"deleteCart","tags":["Carts"],"summary":"Delete a cart and everything it holds","description":"Deletes all of the cart's lines in the shop, with the reservations, seats and stock they held, so others can book them at once. Nothing is left to restore: afterwards the cart answers with status `released` and no lines, and can't be changed or sent to checkout. Make a new cart instead. Only an `active` cart can be deleted: once the customer is in the shop's checkout (`checkout`) or has ordered, it answers 409. A cart you leave alone is deleted the same way when its hold ends.","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_]{1,64}$","example":"johkula","description":"The shop id (its subdomain on johku.com)"},"required":true,"description":"The shop id (its subdomain on johku.com)","name":"shop","in":"path"},{"schema":{"type":"string","pattern":"^crt_[A-Za-z0-9]{16,40}$","example":"crt_8f3k2m9q1x7v4b6n"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Deleted: its lines and what they held are gone"},"400":{"description":"The request is not valid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"VALIDATION_FAILED":{"summary":"VALIDATION_FAILED","value":{"type":"https://api.johku.com/problems/validation-failed","status":400,"code":"VALIDATION_FAILED","title":"The request is not valid","errors":[{"path":"limit","code":"TOO_BIG","message":"Too big: expected number to be <=100"}]}}}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"INVALID_KEY":{"summary":"INVALID_KEY","value":{"type":"https://api.johku.com/problems/invalid-key","status":401,"code":"INVALID_KEY","title":"The API key is not valid"}}}}}},"403":{"description":"The key, integration or shop connection does not allow this","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"SCOPE_NOT_GRANTED":{"summary":"SCOPE_NOT_GRANTED","value":{"type":"https://api.johku.com/problems/scope-not-granted","status":403,"code":"SCOPE_NOT_GRANTED","title":"This shop has not granted orders:read","detail":"Send an access request for the scope."}}}}}},"404":{"description":"No such cart","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"NOT_FOUND":{"summary":"NOT_FOUND","value":{"type":"https://api.johku.com/problems/not-found","status":404,"code":"NOT_FOUND","title":"Not found","detail":"No such cart"}}}}}},"409":{"description":"`CART_NOT_ON_HOLD`: the cart is in the shop's checkout, ordered, released or expired","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"CART_NOT_ON_HOLD":{"summary":"CART_NOT_ON_HOLD","value":{"type":"https://api.johku.com/problems/cart-not-on-hold","title":"The cart is no longer on hold","status":409,"code":"CART_NOT_ON_HOLD"}}}}}},"429":{"description":"A rate limit was hit: see Retry-After and the RateLimit headers","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"RATE_LIMITED":{"summary":"RATE_LIMITED","value":{"type":"https://api.johku.com/problems/rate-limited","status":429,"code":"RATE_LIMITED","title":"Too many requests","detail":"Retry after 12 s."}}}}}},"502":{"description":"The shop backend did not answer as expected","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"BACKEND_ERROR":{"summary":"BACKEND_ERROR","value":{"type":"https://api.johku.com/problems/backend-error","status":502,"code":"BACKEND_ERROR","title":"The shop backend did not answer as expected","detail":"Try again in a moment."}}}}}},"503":{"description":"The endpoint is disabled or busy","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ENDPOINT_DISABLED":{"summary":"ENDPOINT_DISABLED","value":{"type":"https://api.johku.com/problems/endpoint-disabled","status":503,"code":"ENDPOINT_DISABLED","title":"This endpoint is temporarily disabled"}}}}}}}}},"/v1/shops/{shop}/carts/{id}/checkout":{"post":{"operationId":"checkoutCart","tags":["Carts"],"summary":"A link to the shop's own checkout for this cart","description":"The shop's storefront takes the customer details, forms, terms and payment. The customer's earlier basket in that shop is replaced. Once the customer has paid, the shop's confirmation page sends them to `return_url` after a few seconds. From then on the cart can't be changed or deleted; poll GET …/carts/{id} for `order_id`.","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_]{1,64}$","example":"johkula","description":"The shop id (its subdomain on johku.com)"},"required":true,"description":"The shop id (its subdomain on johku.com)","name":"shop","in":"path"},{"schema":{"type":"string","pattern":"^crt_[A-Za-z0-9]{16,40}$","example":"crt_8f3k2m9q1x7v4b6n"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","example":"fi-FI, en;q=0.8","description":"Picks the response language among the shop's locales; the shop default otherwise"},"required":false,"description":"Picks the response language among the shop's locales; the shop default otherwise","name":"Accept-Language","in":"header"},{"schema":{"type":"string","minLength":8,"maxLength":128,"example":"0b9f6c1e-3d0a-4c35-9b8e-2f3f1d6b7a10","description":"Retrying a POST with the same key within 24 hours returns the first result instead of acting twice"},"required":false,"description":"Retrying a POST with the same key within 24 hours returns the first result instead of acting twice","name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutRequest"}}}},"responses":{"200":{"description":"The checkout link","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Checkout"}}}},"400":{"description":"The request is not valid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"VALIDATION_FAILED":{"summary":"VALIDATION_FAILED","value":{"type":"https://api.johku.com/problems/validation-failed","status":400,"code":"VALIDATION_FAILED","title":"The request is not valid","errors":[{"path":"limit","code":"TOO_BIG","message":"Too big: expected number to be <=100"}]}}}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"INVALID_KEY":{"summary":"INVALID_KEY","value":{"type":"https://api.johku.com/problems/invalid-key","status":401,"code":"INVALID_KEY","title":"The API key is not valid"}}}}}},"403":{"description":"The key, integration or shop connection does not allow this","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"SCOPE_NOT_GRANTED":{"summary":"SCOPE_NOT_GRANTED","value":{"type":"https://api.johku.com/problems/scope-not-granted","status":403,"code":"SCOPE_NOT_GRANTED","title":"This shop has not granted orders:read","detail":"Send an access request for the scope."}}}}}},"404":{"description":"No such cart","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"NOT_FOUND":{"summary":"NOT_FOUND","value":{"type":"https://api.johku.com/problems/not-found","status":404,"code":"NOT_FOUND","title":"Not found","detail":"No such cart"}}}}}},"409":{"description":"`CART_NOT_ON_HOLD`: the cart is in the shop's checkout, ordered, released or expired. Or `IDEMPOTENCY_IN_PROGRESS`: a request with this Idempotency-Key is still running; retry after `Retry-After`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"CART_NOT_ON_HOLD":{"summary":"CART_NOT_ON_HOLD","value":{"type":"https://api.johku.com/problems/cart-not-on-hold","title":"The cart is no longer on hold","status":409,"code":"CART_NOT_ON_HOLD"}},"IDEMPOTENCY_IN_PROGRESS":{"summary":"IDEMPOTENCY_IN_PROGRESS","value":{"type":"https://api.johku.com/problems/idempotency-in-progress","title":"A request with this Idempotency-Key is still running","status":409,"code":"IDEMPOTENCY_IN_PROGRESS","detail":"Retry in a moment to get its result."}}}}}},"422":{"description":"A line can't be booked as given: `code` is the booking engine's, `errors[].line` the line. `PRODUCT_NOT_FOUND`: no such published product; `PRODUCT_NOT_BOOKABLE_VIA_API`: book it through its `booking_url`. Or `IDEMPOTENCY_KEY_REUSED`: this Idempotency-Key was used for a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"RESERVATION_INSUFFICIENT_CAPACITY":{"summary":"RESERVATION_INSUFFICIENT_CAPACITY","value":{"type":"https://api.johku.com/problems/reservation-insufficient-capacity","status":422,"code":"RESERVATION_INSUFFICIENT_CAPACITY","title":"The booking can't be made as given","detail":"Line 1: Canoe tour is not available at the selected time.","errors":[{"line":0,"code":"RESERVATION_INSUFFICIENT_CAPACITY","message":"Canoe tour is not available at the selected time."}]}},"PRODUCT_NOT_FOUND":{"summary":"PRODUCT_NOT_FOUND","value":{"type":"https://api.johku.com/problems/product-not-found","title":"The booking can't be made as given","status":422,"code":"PRODUCT_NOT_FOUND","detail":"No published product 259.","errors":[{"line":0,"code":"PRODUCT_NOT_FOUND","message":"No published product 259"}]}},"PRODUCT_NOT_BOOKABLE_VIA_API":{"summary":"PRODUCT_NOT_BOOKABLE_VIA_API","value":{"type":"https://api.johku.com/problems/product-not-bookable-via-api","title":"The booking can't be made as given","status":422,"code":"PRODUCT_NOT_BOOKABLE_VIA_API","detail":"Line 1: Season pass (259) can't be booked through the API. Send the customer to the product's booking_url instead.","errors":[{"line":0,"code":"PRODUCT_NOT_BOOKABLE_VIA_API","message":"Season pass (259) can't be booked through the API."}]}},"IDEMPOTENCY_KEY_REUSED":{"summary":"IDEMPOTENCY_KEY_REUSED","value":{"type":"https://api.johku.com/problems/idempotency-key-reused","title":"This Idempotency-Key was used for a different request","status":422,"code":"IDEMPOTENCY_KEY_REUSED","detail":"Use a new key for a new request."}}}}}},"429":{"description":"A rate limit was hit: see Retry-After and the RateLimit headers","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"RATE_LIMITED":{"summary":"RATE_LIMITED","value":{"type":"https://api.johku.com/problems/rate-limited","status":429,"code":"RATE_LIMITED","title":"Too many requests","detail":"Retry after 12 s."}}}}}},"502":{"description":"The shop backend did not answer as expected","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"BACKEND_ERROR":{"summary":"BACKEND_ERROR","value":{"type":"https://api.johku.com/problems/backend-error","status":502,"code":"BACKEND_ERROR","title":"The shop backend did not answer as expected","detail":"Try again in a moment."}}}}}},"503":{"description":"The endpoint is disabled or busy","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ENDPOINT_DISABLED":{"summary":"ENDPOINT_DISABLED","value":{"type":"https://api.johku.com/problems/endpoint-disabled","status":503,"code":"ENDPOINT_DISABLED","title":"This endpoint is temporarily disabled"}}}}}}}}},"/v1/shops/{shop}/bookings":{"post":{"operationId":"createBooking","tags":["Bookings"],"summary":"Create a confirmed booking paid outside Johku","description":"For resellers who collect the money themselves. Needs the booking:confirm scope, which each shop grants explicitly. Idempotent on `reference`: a repeated reference returns the first booking with `existing: true`.","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_]{1,64}$","example":"johkula","description":"The shop id (its subdomain on johku.com)"},"required":true,"description":"The shop id (its subdomain on johku.com)","name":"shop","in":"path"},{"schema":{"type":"string","example":"fi-FI, en;q=0.8","description":"Picks the response language among the shop's locales; the shop default otherwise"},"required":false,"description":"Picks the response language among the shop's locales; the shop default otherwise","name":"Accept-Language","in":"header"},{"schema":{"type":"string","minLength":8,"maxLength":128,"example":"0b9f6c1e-3d0a-4c35-9b8e-2f3f1d6b7a10","description":"Retrying a POST with the same key within 24 hours returns the first result instead of acting twice"},"required":false,"description":"Retrying a POST with the same key within 24 hours returns the first result instead of acting twice","name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookingRequest"}}}},"responses":{"200":{"description":"A booking with this reference already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Booking"}}}},"201":{"description":"The booking","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Booking"}}}},"400":{"description":"The request is not valid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"VALIDATION_FAILED":{"summary":"VALIDATION_FAILED","value":{"type":"https://api.johku.com/problems/validation-failed","status":400,"code":"VALIDATION_FAILED","title":"The request is not valid","errors":[{"path":"limit","code":"TOO_BIG","message":"Too big: expected number to be <=100"}]}}}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"INVALID_KEY":{"summary":"INVALID_KEY","value":{"type":"https://api.johku.com/problems/invalid-key","status":401,"code":"INVALID_KEY","title":"The API key is not valid"}}}}}},"403":{"description":"The key, integration or shop connection does not allow this","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"SCOPE_NOT_GRANTED":{"summary":"SCOPE_NOT_GRANTED","value":{"type":"https://api.johku.com/problems/scope-not-granted","status":403,"code":"SCOPE_NOT_GRANTED","title":"This shop has not granted orders:read","detail":"Send an access request for the scope."}}}}}},"409":{"description":"`ORDERBUILD_LOCKED`: a booking with this reference is being made right now; retry after `Retry-After`. Or `IDEMPOTENCY_IN_PROGRESS`: a request with this Idempotency-Key is still running; retry after `Retry-After`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ORDERBUILD_LOCKED":{"summary":"ORDERBUILD_LOCKED","value":{"type":"https://api.johku.com/problems/orderbuild-locked","title":"A booking with this reference is being made right now","status":409,"code":"ORDERBUILD_LOCKED","detail":"Retry in a moment to get it."}},"IDEMPOTENCY_IN_PROGRESS":{"summary":"IDEMPOTENCY_IN_PROGRESS","value":{"type":"https://api.johku.com/problems/idempotency-in-progress","title":"A request with this Idempotency-Key is still running","status":409,"code":"IDEMPOTENCY_IN_PROGRESS","detail":"Retry in a moment to get its result."}}}}}},"422":{"description":"A line can't be booked as given: `code` is the booking engine's, `errors[].line` the line. `PRODUCT_NOT_FOUND`: no such published product; `PRODUCT_NOT_BOOKABLE_VIA_API`: book it through its `booking_url`. Or `IDEMPOTENCY_KEY_REUSED`: this Idempotency-Key was used for a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"RESERVATION_INSUFFICIENT_CAPACITY":{"summary":"RESERVATION_INSUFFICIENT_CAPACITY","value":{"type":"https://api.johku.com/problems/reservation-insufficient-capacity","status":422,"code":"RESERVATION_INSUFFICIENT_CAPACITY","title":"The booking can't be made as given","detail":"Line 1: Canoe tour is not available at the selected time.","errors":[{"line":0,"code":"RESERVATION_INSUFFICIENT_CAPACITY","message":"Canoe tour is not available at the selected time."}]}},"PRODUCT_NOT_FOUND":{"summary":"PRODUCT_NOT_FOUND","value":{"type":"https://api.johku.com/problems/product-not-found","title":"The booking can't be made as given","status":422,"code":"PRODUCT_NOT_FOUND","detail":"No published product 259.","errors":[{"line":0,"code":"PRODUCT_NOT_FOUND","message":"No published product 259"}]}},"PRODUCT_NOT_BOOKABLE_VIA_API":{"summary":"PRODUCT_NOT_BOOKABLE_VIA_API","value":{"type":"https://api.johku.com/problems/product-not-bookable-via-api","title":"The booking can't be made as given","status":422,"code":"PRODUCT_NOT_BOOKABLE_VIA_API","detail":"Line 1: Season pass (259) can't be booked through the API. Send the customer to the product's booking_url instead.","errors":[{"line":0,"code":"PRODUCT_NOT_BOOKABLE_VIA_API","message":"Season pass (259) can't be booked through the API."}]}},"IDEMPOTENCY_KEY_REUSED":{"summary":"IDEMPOTENCY_KEY_REUSED","value":{"type":"https://api.johku.com/problems/idempotency-key-reused","title":"This Idempotency-Key was used for a different request","status":422,"code":"IDEMPOTENCY_KEY_REUSED","detail":"Use a new key for a new request."}}}}}},"429":{"description":"A rate limit was hit: see Retry-After and the RateLimit headers","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"RATE_LIMITED":{"summary":"RATE_LIMITED","value":{"type":"https://api.johku.com/problems/rate-limited","status":429,"code":"RATE_LIMITED","title":"Too many requests","detail":"Retry after 12 s."}}}}}},"502":{"description":"The shop backend did not answer as expected","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"BACKEND_ERROR":{"summary":"BACKEND_ERROR","value":{"type":"https://api.johku.com/problems/backend-error","status":502,"code":"BACKEND_ERROR","title":"The shop backend did not answer as expected","detail":"Try again in a moment."}}}}}},"503":{"description":"The endpoint is disabled or busy","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ENDPOINT_DISABLED":{"summary":"ENDPOINT_DISABLED","value":{"type":"https://api.johku.com/problems/endpoint-disabled","status":503,"code":"ENDPOINT_DISABLED","title":"This endpoint is temporarily disabled"}}}}}}}}},"/v1/shops/{shop}/orders":{"get":{"operationId":"listOrders","tags":["Orders"],"summary":"Orders, oldest first","description":"Filter by the day orders were made (created_from, created_to) or, for incremental sync, by updated_since. Times are Europe/Helsinki with an offset.","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_]{1,64}$","example":"johkula","description":"The shop id (its subdomain on johku.com)"},"required":true,"description":"The shop id (its subdomain on johku.com)","name":"shop","in":"path"},{"schema":{"type":"string","description":"The `next_cursor` of the previous page"},"required":false,"description":"The `next_cursor` of the previous page","name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","example":"2026-12-24T14:30:00+02:00","description":"Orders created or changed at or after this time"},"required":false,"description":"Orders created or changed at or after this time","name":"updated_since","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-24","description":"Orders made on or after this day (with created_to)"},"required":false,"description":"Orders made on or after this day (with created_to)","name":"created_from","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-24","description":"Orders made on or before this day (with created_from)"},"required":false,"description":"Orders made on or before this day (with created_from)","name":"created_to","in":"query"}],"responses":{"200":{"description":"A page of orders","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderPage"}}}},"400":{"description":"The request is not valid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"VALIDATION_FAILED":{"summary":"VALIDATION_FAILED","value":{"type":"https://api.johku.com/problems/validation-failed","status":400,"code":"VALIDATION_FAILED","title":"The request is not valid","errors":[{"path":"limit","code":"TOO_BIG","message":"Too big: expected number to be <=100"}]}}}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"INVALID_KEY":{"summary":"INVALID_KEY","value":{"type":"https://api.johku.com/problems/invalid-key","status":401,"code":"INVALID_KEY","title":"The API key is not valid"}}}}}},"403":{"description":"The key, integration or shop connection does not allow this","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"SCOPE_NOT_GRANTED":{"summary":"SCOPE_NOT_GRANTED","value":{"type":"https://api.johku.com/problems/scope-not-granted","status":403,"code":"SCOPE_NOT_GRANTED","title":"This shop has not granted orders:read","detail":"Send an access request for the scope."}}}}}},"429":{"description":"A rate limit was hit: see Retry-After and the RateLimit headers","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"RATE_LIMITED":{"summary":"RATE_LIMITED","value":{"type":"https://api.johku.com/problems/rate-limited","status":429,"code":"RATE_LIMITED","title":"Too many requests","detail":"Retry after 12 s."}}}}}},"502":{"description":"The shop backend did not answer as expected","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"BACKEND_ERROR":{"summary":"BACKEND_ERROR","value":{"type":"https://api.johku.com/problems/backend-error","status":502,"code":"BACKEND_ERROR","title":"The shop backend did not answer as expected","detail":"Try again in a moment."}}}}}},"503":{"description":"The endpoint is disabled or busy","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ENDPOINT_DISABLED":{"summary":"ENDPOINT_DISABLED","value":{"type":"https://api.johku.com/problems/endpoint-disabled","status":503,"code":"ENDPOINT_DISABLED","title":"This endpoint is temporarily disabled"}}}}}}}}},"/v1/shops/{shop}/orders/{id}":{"get":{"operationId":"getOrder","tags":["Orders"],"summary":"One order with its lines and reservations","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_]{1,64}$","example":"johkula","description":"The shop id (its subdomain on johku.com)"},"required":true,"description":"The shop id (its subdomain on johku.com)","name":"shop","in":"path"},{"schema":{"type":"integer","exclusiveMinimum":0,"example":259},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"400":{"description":"The request is not valid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"VALIDATION_FAILED":{"summary":"VALIDATION_FAILED","value":{"type":"https://api.johku.com/problems/validation-failed","status":400,"code":"VALIDATION_FAILED","title":"The request is not valid","errors":[{"path":"limit","code":"TOO_BIG","message":"Too big: expected number to be <=100"}]}}}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"INVALID_KEY":{"summary":"INVALID_KEY","value":{"type":"https://api.johku.com/problems/invalid-key","status":401,"code":"INVALID_KEY","title":"The API key is not valid"}}}}}},"403":{"description":"The key, integration or shop connection does not allow this","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"SCOPE_NOT_GRANTED":{"summary":"SCOPE_NOT_GRANTED","value":{"type":"https://api.johku.com/problems/scope-not-granted","status":403,"code":"SCOPE_NOT_GRANTED","title":"This shop has not granted orders:read","detail":"Send an access request for the scope."}}}}}},"404":{"description":"No such order","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"NOT_FOUND":{"summary":"NOT_FOUND","value":{"type":"https://api.johku.com/problems/not-found","status":404,"code":"NOT_FOUND","title":"Not found","detail":"No such order"}}}}}},"429":{"description":"A rate limit was hit: see Retry-After and the RateLimit headers","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"RATE_LIMITED":{"summary":"RATE_LIMITED","value":{"type":"https://api.johku.com/problems/rate-limited","status":429,"code":"RATE_LIMITED","title":"Too many requests","detail":"Retry after 12 s."}}}}}},"502":{"description":"The shop backend did not answer as expected","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"BACKEND_ERROR":{"summary":"BACKEND_ERROR","value":{"type":"https://api.johku.com/problems/backend-error","status":502,"code":"BACKEND_ERROR","title":"The shop backend did not answer as expected","detail":"Try again in a moment."}}}}}},"503":{"description":"The endpoint is disabled or busy","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ENDPOINT_DISABLED":{"summary":"ENDPOINT_DISABLED","value":{"type":"https://api.johku.com/problems/endpoint-disabled","status":503,"code":"ENDPOINT_DISABLED","title":"This endpoint is temporarily disabled"}}}}}}}}},"/v1/shops/{shop}/orders/lookup":{"post":{"operationId":"lookupOrder","tags":["Orders"],"summary":"Find an order by the code its customer has","description":"The code is the order's identifier, which the shop's messages can give the customer: a product message's `{orderidentifier}`, for example in a link to your service. Use it to check a code a customer brings, such as access bought in the shop, without syncing the shop's orders. Only someone who has the order's messages knows its code. The code goes in the body, so it stays out of URLs and logs. Costs 2 from your quota.","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_]{1,64}$","example":"johkula","description":"The shop id (its subdomain on johku.com)"},"required":true,"description":"The shop id (its subdomain on johku.com)","name":"shop","in":"path"},{"schema":{"type":"string","minLength":8,"maxLength":128,"example":"0b9f6c1e-3d0a-4c35-9b8e-2f3f1d6b7a10","description":"Retrying a POST with the same key within 24 hours returns the first result instead of acting twice"},"required":false,"description":"Retrying a POST with the same key within 24 hours returns the first result instead of acting twice","name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderLookup"}}}},"responses":{"200":{"description":"The order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"400":{"description":"The request is not valid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"VALIDATION_FAILED":{"summary":"VALIDATION_FAILED","value":{"type":"https://api.johku.com/problems/validation-failed","status":400,"code":"VALIDATION_FAILED","title":"The request is not valid","errors":[{"path":"limit","code":"TOO_BIG","message":"Too big: expected number to be <=100"}]}}}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"INVALID_KEY":{"summary":"INVALID_KEY","value":{"type":"https://api.johku.com/problems/invalid-key","status":401,"code":"INVALID_KEY","title":"The API key is not valid"}}}}}},"403":{"description":"The key, integration or shop connection does not allow this","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"SCOPE_NOT_GRANTED":{"summary":"SCOPE_NOT_GRANTED","value":{"type":"https://api.johku.com/problems/scope-not-granted","status":403,"code":"SCOPE_NOT_GRANTED","title":"This shop has not granted orders:read","detail":"Send an access request for the scope."}}}}}},"404":{"description":"No order has this code","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"NOT_FOUND":{"summary":"NOT_FOUND","value":{"type":"https://api.johku.com/problems/not-found","status":404,"code":"NOT_FOUND","title":"Not found","detail":"No order has this code"}}}}}},"409":{"description":"`IDEMPOTENCY_IN_PROGRESS`: a request with this Idempotency-Key is still running; retry after `Retry-After`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"IDEMPOTENCY_IN_PROGRESS":{"summary":"IDEMPOTENCY_IN_PROGRESS","value":{"type":"https://api.johku.com/problems/idempotency-in-progress","title":"A request with this Idempotency-Key is still running","status":409,"code":"IDEMPOTENCY_IN_PROGRESS","detail":"Retry in a moment to get its result."}}}}}},"422":{"description":"`IDEMPOTENCY_KEY_REUSED`: this Idempotency-Key was used for a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"IDEMPOTENCY_KEY_REUSED":{"summary":"IDEMPOTENCY_KEY_REUSED","value":{"type":"https://api.johku.com/problems/idempotency-key-reused","title":"This Idempotency-Key was used for a different request","status":422,"code":"IDEMPOTENCY_KEY_REUSED","detail":"Use a new key for a new request."}}}}}},"429":{"description":"A rate limit was hit: see Retry-After and the RateLimit headers","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"RATE_LIMITED":{"summary":"RATE_LIMITED","value":{"type":"https://api.johku.com/problems/rate-limited","status":429,"code":"RATE_LIMITED","title":"Too many requests","detail":"Retry after 12 s."}}}}}},"502":{"description":"The shop backend did not answer as expected","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"BACKEND_ERROR":{"summary":"BACKEND_ERROR","value":{"type":"https://api.johku.com/problems/backend-error","status":502,"code":"BACKEND_ERROR","title":"The shop backend did not answer as expected","detail":"Try again in a moment."}}}}}},"503":{"description":"The endpoint is disabled or busy","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ENDPOINT_DISABLED":{"summary":"ENDPOINT_DISABLED","value":{"type":"https://api.johku.com/problems/endpoint-disabled","status":503,"code":"ENDPOINT_DISABLED","title":"This endpoint is temporarily disabled"}}}}}}}}},"/v1/shops/{shop}/reservations":{"get":{"operationId":"listReservations","tags":["Orders"],"summary":"Reservations starting in a date window","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_]{1,64}$","example":"johkula","description":"The shop id (its subdomain on johku.com)"},"required":true,"description":"The shop id (its subdomain on johku.com)","name":"shop","in":"path"},{"schema":{"type":"string","description":"The `next_cursor` of the previous page"},"required":false,"description":"The `next_cursor` of the previous page","name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-24","description":"Reservations starting on or after this day (default today)"},"required":false,"description":"Reservations starting on or after this day (default today)","name":"from","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-24","description":"And on or before this day (default `from` + 30 days, at most + 93)"},"required":false,"description":"And on or before this day (default `from` + 30 days, at most + 93)","name":"to","in":"query"}],"responses":{"200":{"description":"A page of reservations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReservationPage"}}}},"400":{"description":"The request is not valid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"VALIDATION_FAILED":{"summary":"VALIDATION_FAILED","value":{"type":"https://api.johku.com/problems/validation-failed","status":400,"code":"VALIDATION_FAILED","title":"The request is not valid","errors":[{"path":"limit","code":"TOO_BIG","message":"Too big: expected number to be <=100"}]}}}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"INVALID_KEY":{"summary":"INVALID_KEY","value":{"type":"https://api.johku.com/problems/invalid-key","status":401,"code":"INVALID_KEY","title":"The API key is not valid"}}}}}},"403":{"description":"The key, integration or shop connection does not allow this","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"SCOPE_NOT_GRANTED":{"summary":"SCOPE_NOT_GRANTED","value":{"type":"https://api.johku.com/problems/scope-not-granted","status":403,"code":"SCOPE_NOT_GRANTED","title":"This shop has not granted orders:read","detail":"Send an access request for the scope."}}}}}},"429":{"description":"A rate limit was hit: see Retry-After and the RateLimit headers","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"RATE_LIMITED":{"summary":"RATE_LIMITED","value":{"type":"https://api.johku.com/problems/rate-limited","status":429,"code":"RATE_LIMITED","title":"Too many requests","detail":"Retry after 12 s."}}}}}},"502":{"description":"The shop backend did not answer as expected","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"BACKEND_ERROR":{"summary":"BACKEND_ERROR","value":{"type":"https://api.johku.com/problems/backend-error","status":502,"code":"BACKEND_ERROR","title":"The shop backend did not answer as expected","detail":"Try again in a moment."}}}}}},"503":{"description":"The endpoint is disabled or busy","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ENDPOINT_DISABLED":{"summary":"ENDPOINT_DISABLED","value":{"type":"https://api.johku.com/problems/endpoint-disabled","status":503,"code":"ENDPOINT_DISABLED","title":"This endpoint is temporarily disabled"}}}}}}}}},"/v1/shops/{shop}/customers":{"get":{"operationId":"listCustomers","tags":["Customers"],"summary":"The shop's customer register","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_]{1,64}$","example":"johkula","description":"The shop id (its subdomain on johku.com)"},"required":true,"description":"The shop id (its subdomain on johku.com)","name":"shop","in":"path"},{"schema":{"type":"string","description":"The `next_cursor` of the previous page"},"required":false,"description":"The `next_cursor` of the previous page","name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","maxLength":200,"description":"Matches name, email or phone"},"required":false,"description":"Matches name, email or phone","name":"q","in":"query"}],"responses":{"200":{"description":"A page of customers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerPage"}}}},"400":{"description":"The request is not valid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"VALIDATION_FAILED":{"summary":"VALIDATION_FAILED","value":{"type":"https://api.johku.com/problems/validation-failed","status":400,"code":"VALIDATION_FAILED","title":"The request is not valid","errors":[{"path":"limit","code":"TOO_BIG","message":"Too big: expected number to be <=100"}]}}}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"INVALID_KEY":{"summary":"INVALID_KEY","value":{"type":"https://api.johku.com/problems/invalid-key","status":401,"code":"INVALID_KEY","title":"The API key is not valid"}}}}}},"403":{"description":"The key, integration or shop connection does not allow this","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"SCOPE_NOT_GRANTED":{"summary":"SCOPE_NOT_GRANTED","value":{"type":"https://api.johku.com/problems/scope-not-granted","status":403,"code":"SCOPE_NOT_GRANTED","title":"This shop has not granted orders:read","detail":"Send an access request for the scope."}}}}}},"429":{"description":"A rate limit was hit: see Retry-After and the RateLimit headers","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"RATE_LIMITED":{"summary":"RATE_LIMITED","value":{"type":"https://api.johku.com/problems/rate-limited","status":429,"code":"RATE_LIMITED","title":"Too many requests","detail":"Retry after 12 s."}}}}}},"502":{"description":"The shop backend did not answer as expected","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"BACKEND_ERROR":{"summary":"BACKEND_ERROR","value":{"type":"https://api.johku.com/problems/backend-error","status":502,"code":"BACKEND_ERROR","title":"The shop backend did not answer as expected","detail":"Try again in a moment."}}}}}},"503":{"description":"The endpoint is disabled or busy","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ENDPOINT_DISABLED":{"summary":"ENDPOINT_DISABLED","value":{"type":"https://api.johku.com/problems/endpoint-disabled","status":503,"code":"ENDPOINT_DISABLED","title":"This endpoint is temporarily disabled"}}}}}}}}},"/v1/shops/{shop}/customers/{id}":{"get":{"operationId":"getCustomer","tags":["Customers"],"summary":"One customer","description":"Each read is written to the shop's audit log.","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_]{1,64}$","example":"johkula","description":"The shop id (its subdomain on johku.com)"},"required":true,"description":"The shop id (its subdomain on johku.com)","name":"shop","in":"path"},{"schema":{"type":"integer","exclusiveMinimum":0,"example":259},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The customer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"}}}},"400":{"description":"The request is not valid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"VALIDATION_FAILED":{"summary":"VALIDATION_FAILED","value":{"type":"https://api.johku.com/problems/validation-failed","status":400,"code":"VALIDATION_FAILED","title":"The request is not valid","errors":[{"path":"limit","code":"TOO_BIG","message":"Too big: expected number to be <=100"}]}}}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"INVALID_KEY":{"summary":"INVALID_KEY","value":{"type":"https://api.johku.com/problems/invalid-key","status":401,"code":"INVALID_KEY","title":"The API key is not valid"}}}}}},"403":{"description":"The key, integration or shop connection does not allow this","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"SCOPE_NOT_GRANTED":{"summary":"SCOPE_NOT_GRANTED","value":{"type":"https://api.johku.com/problems/scope-not-granted","status":403,"code":"SCOPE_NOT_GRANTED","title":"This shop has not granted orders:read","detail":"Send an access request for the scope."}}}}}},"404":{"description":"No such customer","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"NOT_FOUND":{"summary":"NOT_FOUND","value":{"type":"https://api.johku.com/problems/not-found","status":404,"code":"NOT_FOUND","title":"Not found","detail":"No such customer"}}}}}},"429":{"description":"A rate limit was hit: see Retry-After and the RateLimit headers","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"RATE_LIMITED":{"summary":"RATE_LIMITED","value":{"type":"https://api.johku.com/problems/rate-limited","status":429,"code":"RATE_LIMITED","title":"Too many requests","detail":"Retry after 12 s."}}}}}},"502":{"description":"The shop backend did not answer as expected","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"BACKEND_ERROR":{"summary":"BACKEND_ERROR","value":{"type":"https://api.johku.com/problems/backend-error","status":502,"code":"BACKEND_ERROR","title":"The shop backend did not answer as expected","detail":"Try again in a moment."}}}}}},"503":{"description":"The endpoint is disabled or busy","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ENDPOINT_DISABLED":{"summary":"ENDPOINT_DISABLED","value":{"type":"https://api.johku.com/problems/endpoint-disabled","status":503,"code":"ENDPOINT_DISABLED","title":"This endpoint is temporarily disabled"}}}}}}}}},"/v1/shops/{shop}/reports":{"post":{"operationId":"createReport","tags":["Reports"],"summary":"Start a sales report","description":"Reports run in the background: poll GET …/reports/{id} until status is done or failed. Results are kept for 7 days. One request costs 10 from your quota.","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_]{1,64}$","example":"johkula","description":"The shop id (its subdomain on johku.com)"},"required":true,"description":"The shop id (its subdomain on johku.com)","name":"shop","in":"path"},{"schema":{"type":"string","minLength":8,"maxLength":128,"example":"0b9f6c1e-3d0a-4c35-9b8e-2f3f1d6b7a10","description":"Retrying a POST with the same key within 24 hours returns the first result instead of acting twice"},"required":false,"description":"Retrying a POST with the same key within 24 hours returns the first result instead of acting twice","name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportRequest"}}}},"responses":{"202":{"description":"The report was queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportJob"}}}},"400":{"description":"The request is not valid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"VALIDATION_FAILED":{"summary":"VALIDATION_FAILED","value":{"type":"https://api.johku.com/problems/validation-failed","status":400,"code":"VALIDATION_FAILED","title":"The request is not valid","errors":[{"path":"limit","code":"TOO_BIG","message":"Too big: expected number to be <=100"}]}}}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"INVALID_KEY":{"summary":"INVALID_KEY","value":{"type":"https://api.johku.com/problems/invalid-key","status":401,"code":"INVALID_KEY","title":"The API key is not valid"}}}}}},"403":{"description":"The key, integration or shop connection does not allow this","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"SCOPE_NOT_GRANTED":{"summary":"SCOPE_NOT_GRANTED","value":{"type":"https://api.johku.com/problems/scope-not-granted","status":403,"code":"SCOPE_NOT_GRANTED","title":"This shop has not granted orders:read","detail":"Send an access request for the scope."}}}}}},"409":{"description":"`IDEMPOTENCY_IN_PROGRESS`: a request with this Idempotency-Key is still running; retry after `Retry-After`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"IDEMPOTENCY_IN_PROGRESS":{"summary":"IDEMPOTENCY_IN_PROGRESS","value":{"type":"https://api.johku.com/problems/idempotency-in-progress","title":"A request with this Idempotency-Key is still running","status":409,"code":"IDEMPOTENCY_IN_PROGRESS","detail":"Retry in a moment to get its result."}}}}}},"422":{"description":"`IDEMPOTENCY_KEY_REUSED`: this Idempotency-Key was used for a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"IDEMPOTENCY_KEY_REUSED":{"summary":"IDEMPOTENCY_KEY_REUSED","value":{"type":"https://api.johku.com/problems/idempotency-key-reused","title":"This Idempotency-Key was used for a different request","status":422,"code":"IDEMPOTENCY_KEY_REUSED","detail":"Use a new key for a new request."}}}}}},"429":{"description":"A rate limit was hit: see Retry-After and the RateLimit headers","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"RATE_LIMITED":{"summary":"RATE_LIMITED","value":{"type":"https://api.johku.com/problems/rate-limited","status":429,"code":"RATE_LIMITED","title":"Too many requests","detail":"Retry after 12 s."}}}}}},"502":{"description":"The shop backend did not answer as expected","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"BACKEND_ERROR":{"summary":"BACKEND_ERROR","value":{"type":"https://api.johku.com/problems/backend-error","status":502,"code":"BACKEND_ERROR","title":"The shop backend did not answer as expected","detail":"Try again in a moment."}}}}}},"503":{"description":"The endpoint is disabled or busy","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ENDPOINT_DISABLED":{"summary":"ENDPOINT_DISABLED","value":{"type":"https://api.johku.com/problems/endpoint-disabled","status":503,"code":"ENDPOINT_DISABLED","title":"This endpoint is temporarily disabled"}}}}}}}}},"/v1/shops/{shop}/reports/{id}":{"get":{"operationId":"getReport","tags":["Reports"],"summary":"A report's status, and its result once done","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_]{1,64}$","example":"johkula","description":"The shop id (its subdomain on johku.com)"},"required":true,"description":"The shop id (its subdomain on johku.com)","name":"shop","in":"path"},{"schema":{"type":"string","pattern":"^[a-f0-9]{32}$","example":"6a0f3c2e9b1d4f7a8c5e2b0d1f3a5c7e"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Report"}}}},"400":{"description":"The request is not valid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"VALIDATION_FAILED":{"summary":"VALIDATION_FAILED","value":{"type":"https://api.johku.com/problems/validation-failed","status":400,"code":"VALIDATION_FAILED","title":"The request is not valid","errors":[{"path":"limit","code":"TOO_BIG","message":"Too big: expected number to be <=100"}]}}}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"INVALID_KEY":{"summary":"INVALID_KEY","value":{"type":"https://api.johku.com/problems/invalid-key","status":401,"code":"INVALID_KEY","title":"The API key is not valid"}}}}}},"403":{"description":"The key, integration or shop connection does not allow this","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"SCOPE_NOT_GRANTED":{"summary":"SCOPE_NOT_GRANTED","value":{"type":"https://api.johku.com/problems/scope-not-granted","status":403,"code":"SCOPE_NOT_GRANTED","title":"This shop has not granted orders:read","detail":"Send an access request for the scope."}}}}}},"404":{"description":"No such report, or it has expired","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"NOT_FOUND":{"summary":"NOT_FOUND","value":{"type":"https://api.johku.com/problems/not-found","status":404,"code":"NOT_FOUND","title":"Not found","detail":"No such report, or it has expired"}}}}}},"429":{"description":"A rate limit was hit: see Retry-After and the RateLimit headers","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"RATE_LIMITED":{"summary":"RATE_LIMITED","value":{"type":"https://api.johku.com/problems/rate-limited","status":429,"code":"RATE_LIMITED","title":"Too many requests","detail":"Retry after 12 s."}}}}}},"502":{"description":"The shop backend did not answer as expected","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"BACKEND_ERROR":{"summary":"BACKEND_ERROR","value":{"type":"https://api.johku.com/problems/backend-error","status":502,"code":"BACKEND_ERROR","title":"The shop backend did not answer as expected","detail":"Try again in a moment."}}}}}},"503":{"description":"The endpoint is disabled or busy","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ENDPOINT_DISABLED":{"summary":"ENDPOINT_DISABLED","value":{"type":"https://api.johku.com/problems/endpoint-disabled","status":503,"code":"ENDPOINT_DISABLED","title":"This endpoint is temporarily disabled"}}}}}}}}},"/v1/access-requests":{"post":{"operationId":"createAccessRequest","tags":["Access"],"summary":"Ask a shop to connect your integration","description":"The shop's admins see your integration's name, the scopes and your reason, and approve or deny. Needs a live secret key of a pilot or verified partner.","parameters":[{"schema":{"type":"string","minLength":8,"maxLength":128,"example":"0b9f6c1e-3d0a-4c35-9b8e-2f3f1d6b7a10","description":"Retrying a POST with the same key within 24 hours returns the first result instead of acting twice"},"required":false,"description":"Retrying a POST with the same key within 24 hours returns the first result instead of acting twice","name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessRequestInput"}}}},"responses":{"201":{"description":"The request was sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessRequest"}}}},"400":{"description":"The request is not valid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"VALIDATION_FAILED":{"summary":"VALIDATION_FAILED","value":{"type":"https://api.johku.com/problems/validation-failed","status":400,"code":"VALIDATION_FAILED","title":"The request is not valid","errors":[{"path":"limit","code":"TOO_BIG","message":"Too big: expected number to be <=100"}]}}}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"INVALID_KEY":{"summary":"INVALID_KEY","value":{"type":"https://api.johku.com/problems/invalid-key","status":401,"code":"INVALID_KEY","title":"The API key is not valid"}}}}}},"403":{"description":"The key, integration or shop connection does not allow this","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"SCOPE_NOT_GRANTED":{"summary":"SCOPE_NOT_GRANTED","value":{"type":"https://api.johku.com/problems/scope-not-granted","status":403,"code":"SCOPE_NOT_GRANTED","title":"This shop has not granted orders:read","detail":"Send an access request for the scope."}}}}}},"409":{"description":"`CONNECTION_EXISTS`: your integration is already connected to this shop. Or `IDEMPOTENCY_IN_PROGRESS`: a request with this Idempotency-Key is still running; retry after `Retry-After`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"CONNECTION_EXISTS":{"summary":"CONNECTION_EXISTS","value":{"type":"https://api.johku.com/problems/connection-exists","title":"Your integration is already connected to this shop","status":409,"code":"CONNECTION_EXISTS"}},"IDEMPOTENCY_IN_PROGRESS":{"summary":"IDEMPOTENCY_IN_PROGRESS","value":{"type":"https://api.johku.com/problems/idempotency-in-progress","title":"A request with this Idempotency-Key is still running","status":409,"code":"IDEMPOTENCY_IN_PROGRESS","detail":"Retry in a moment to get its result."}}}}}},"422":{"description":"`PARTNER_NOT_LIVE`, `PARTNER_PILOT_LIMIT`, `CONNECTION_SCOPE_NOT_ALLOWED`: the partner, integration or shop can't take this request. Or `IDEMPOTENCY_KEY_REUSED`: this Idempotency-Key was used for a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"PARTNER_NOT_LIVE":{"summary":"PARTNER_NOT_LIVE","value":{"type":"https://api.johku.com/problems/partner-not-live","title":"The access request can't be made","status":422,"code":"PARTNER_NOT_LIVE"}},"PARTNER_PILOT_LIMIT":{"summary":"PARTNER_PILOT_LIMIT","value":{"type":"https://api.johku.com/problems/partner-pilot-limit","title":"The access request can't be made","status":422,"code":"PARTNER_PILOT_LIMIT"}},"CONNECTION_SCOPE_NOT_ALLOWED":{"summary":"CONNECTION_SCOPE_NOT_ALLOWED","value":{"type":"https://api.johku.com/problems/connection-scope-not-allowed","title":"The access request can't be made","status":422,"code":"CONNECTION_SCOPE_NOT_ALLOWED"}},"IDEMPOTENCY_KEY_REUSED":{"summary":"IDEMPOTENCY_KEY_REUSED","value":{"type":"https://api.johku.com/problems/idempotency-key-reused","title":"This Idempotency-Key was used for a different request","status":422,"code":"IDEMPOTENCY_KEY_REUSED","detail":"Use a new key for a new request."}}}}}},"429":{"description":"A rate limit was hit: see Retry-After and the RateLimit headers","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"RATE_LIMITED":{"summary":"RATE_LIMITED","value":{"type":"https://api.johku.com/problems/rate-limited","status":429,"code":"RATE_LIMITED","title":"Too many requests","detail":"Retry after 12 s."}}}}}},"502":{"description":"The shop backend did not answer as expected","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"BACKEND_ERROR":{"summary":"BACKEND_ERROR","value":{"type":"https://api.johku.com/problems/backend-error","status":502,"code":"BACKEND_ERROR","title":"The shop backend did not answer as expected","detail":"Try again in a moment."}}}}}},"503":{"description":"The endpoint is disabled or busy","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ENDPOINT_DISABLED":{"summary":"ENDPOINT_DISABLED","value":{"type":"https://api.johku.com/problems/endpoint-disabled","status":503,"code":"ENDPOINT_DISABLED","title":"This endpoint is temporarily disabled"}}}}}}}},"get":{"operationId":"listAccessRequests","tags":["Access"],"summary":"Your integration's access requests","responses":{"200":{"description":"The requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessRequestList"}}}},"400":{"description":"The request is not valid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"VALIDATION_FAILED":{"summary":"VALIDATION_FAILED","value":{"type":"https://api.johku.com/problems/validation-failed","status":400,"code":"VALIDATION_FAILED","title":"The request is not valid","errors":[{"path":"limit","code":"TOO_BIG","message":"Too big: expected number to be <=100"}]}}}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"INVALID_KEY":{"summary":"INVALID_KEY","value":{"type":"https://api.johku.com/problems/invalid-key","status":401,"code":"INVALID_KEY","title":"The API key is not valid"}}}}}},"403":{"description":"The key, integration or shop connection does not allow this","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"SCOPE_NOT_GRANTED":{"summary":"SCOPE_NOT_GRANTED","value":{"type":"https://api.johku.com/problems/scope-not-granted","status":403,"code":"SCOPE_NOT_GRANTED","title":"This shop has not granted orders:read","detail":"Send an access request for the scope."}}}}}},"429":{"description":"A rate limit was hit: see Retry-After and the RateLimit headers","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"RATE_LIMITED":{"summary":"RATE_LIMITED","value":{"type":"https://api.johku.com/problems/rate-limited","status":429,"code":"RATE_LIMITED","title":"Too many requests","detail":"Retry after 12 s."}}}}}},"502":{"description":"The shop backend did not answer as expected","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"BACKEND_ERROR":{"summary":"BACKEND_ERROR","value":{"type":"https://api.johku.com/problems/backend-error","status":502,"code":"BACKEND_ERROR","title":"The shop backend did not answer as expected","detail":"Try again in a moment."}}}}}},"503":{"description":"The endpoint is disabled or busy","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ENDPOINT_DISABLED":{"summary":"ENDPOINT_DISABLED","value":{"type":"https://api.johku.com/problems/endpoint-disabled","status":503,"code":"ENDPOINT_DISABLED","title":"This endpoint is temporarily disabled"}}}}}}}}},"/v1/connections":{"get":{"operationId":"listConnections","tags":["Access"],"summary":"The shops your integration is connected to, with their scopes","responses":{"200":{"description":"The connections","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionList"}}}},"400":{"description":"The request is not valid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"VALIDATION_FAILED":{"summary":"VALIDATION_FAILED","value":{"type":"https://api.johku.com/problems/validation-failed","status":400,"code":"VALIDATION_FAILED","title":"The request is not valid","errors":[{"path":"limit","code":"TOO_BIG","message":"Too big: expected number to be <=100"}]}}}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"INVALID_KEY":{"summary":"INVALID_KEY","value":{"type":"https://api.johku.com/problems/invalid-key","status":401,"code":"INVALID_KEY","title":"The API key is not valid"}}}}}},"403":{"description":"The key, integration or shop connection does not allow this","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"SCOPE_NOT_GRANTED":{"summary":"SCOPE_NOT_GRANTED","value":{"type":"https://api.johku.com/problems/scope-not-granted","status":403,"code":"SCOPE_NOT_GRANTED","title":"This shop has not granted orders:read","detail":"Send an access request for the scope."}}}}}},"429":{"description":"A rate limit was hit: see Retry-After and the RateLimit headers","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"RATE_LIMITED":{"summary":"RATE_LIMITED","value":{"type":"https://api.johku.com/problems/rate-limited","status":429,"code":"RATE_LIMITED","title":"Too many requests","detail":"Retry after 12 s."}}}}}},"502":{"description":"The shop backend did not answer as expected","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"BACKEND_ERROR":{"summary":"BACKEND_ERROR","value":{"type":"https://api.johku.com/problems/backend-error","status":502,"code":"BACKEND_ERROR","title":"The shop backend did not answer as expected","detail":"Try again in a moment."}}}}}},"503":{"description":"The endpoint is disabled or busy","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ENDPOINT_DISABLED":{"summary":"ENDPOINT_DISABLED","value":{"type":"https://api.johku.com/problems/endpoint-disabled","status":503,"code":"ENDPOINT_DISABLED","title":"This endpoint is temporarily disabled"}}}}}}}}},"/v1/atlas/products":{"get":{"operationId":"searchAtlasProducts","tags":["Atlas"],"summary":"Search products across Johku shops","description":"Every live Johku shop that hasn't opted out, with no shop connection needed. With dates, only products bookable then are listed, with their availability and `stay_total`. To book one, use the shop's own endpoints with `shop` and `product_id` once the shop has connected your integration, or send the customer to `booking_url`. Pages cover the first 250 ranked results; narrow the filters to see beyond them.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-24","description":"Arrival, or the first day of the range"},"required":false,"description":"Arrival, or the first day of the range","name":"start_date","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-24","description":"Departure, or the last day of the range"},"required":false,"description":"Departure, or the last day of the range","name":"end_date","in":"query"},{"schema":{"type":"integer","exclusiveMinimum":0,"maximum":1000},"required":false,"name":"participants","in":"query"},{"schema":{"type":"integer","exclusiveMinimum":0,"maximum":1000,"description":"Inventory units, e.g. cabins"},"required":false,"description":"Inventory units, e.g. cabins","name":"units","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":200,"description":"Keywords; leave out to search by the filters alone","example":"sauna"},"required":false,"description":"Keywords; leave out to search by the filters alone","name":"q","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":100,"description":"A town, village or resort in Finland","example":"Ruka"},"required":false,"description":"A town, village or resort in Finland","name":"place","in":"query"},{"schema":{"type":["number","null"],"minimum":-90,"maximum":90},"required":false,"name":"lat","in":"query"},{"schema":{"type":["number","null"],"minimum":-180,"maximum":180},"required":false,"name":"lng","in":"query"},{"schema":{"type":"number","exclusiveMinimum":0,"maximum":1000,"description":"Around place (about 40 km by default) or lat/lng"},"required":false,"description":"Around place (about 40 km by default) or lat/lng","name":"radius_km","in":"query"},{"schema":{"type":"string","maxLength":500,"description":"Comma-separated types from GET /v1/atlas/product-types","example":"accommodation,experience"},"required":false,"description":"Comma-separated types from GET /v1/atlas/product-types","name":"types","in":"query"},{"schema":{"type":"string","maxLength":500,"description":"Comma-separated amenities that must all match","example":"sauna"},"required":false,"description":"Comma-separated amenities that must all match","name":"attributes","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"description":"Minimum public from-price in cents"},"required":false,"description":"Minimum public from-price in cents","name":"price_min","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"description":"Maximum public from-price in cents"},"required":false,"description":"Maximum public from-price in cents","name":"price_max","in":"query"},{"schema":{"type":"string","enum":["relevance","distance"],"default":"relevance","description":"distance: nearest first, which needs place or lat/lng and takes no q, attributes or price filters"},"required":false,"description":"distance: nearest first, which needs place or lat/lng and takes no q, attributes or price filters","name":"sort","in":"query"},{"schema":{"type":"string","description":"The `next_cursor` of the previous page"},"required":false,"description":"The `next_cursor` of the previous page","name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"A page of products","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AtlasProductPage"}}}},"400":{"description":"The request is not valid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"VALIDATION_FAILED":{"summary":"VALIDATION_FAILED","value":{"type":"https://api.johku.com/problems/validation-failed","status":400,"code":"VALIDATION_FAILED","title":"The request is not valid","errors":[{"path":"limit","code":"TOO_BIG","message":"Too big: expected number to be <=100"}]}}}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"INVALID_KEY":{"summary":"INVALID_KEY","value":{"type":"https://api.johku.com/problems/invalid-key","status":401,"code":"INVALID_KEY","title":"The API key is not valid"}}}}}},"403":{"description":"The key, integration or shop connection does not allow this","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"SCOPE_NOT_GRANTED":{"summary":"SCOPE_NOT_GRANTED","value":{"type":"https://api.johku.com/problems/scope-not-granted","status":403,"code":"SCOPE_NOT_GRANTED","title":"This shop has not granted orders:read","detail":"Send an access request for the scope."}}}}}},"429":{"description":"A rate limit was hit: see Retry-After and the RateLimit headers","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"RATE_LIMITED":{"summary":"RATE_LIMITED","value":{"type":"https://api.johku.com/problems/rate-limited","status":429,"code":"RATE_LIMITED","title":"Too many requests","detail":"Retry after 12 s."}}}}}},"502":{"description":"`ATLAS_ERROR`: Atlas did not answer as expected","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ATLAS_ERROR":{"summary":"ATLAS_ERROR","value":{"type":"https://api.johku.com/problems/atlas-error","title":"Atlas did not answer as expected","status":502,"code":"ATLAS_ERROR","detail":"Try again in a moment."}}}}}},"503":{"description":"The endpoint is disabled or busy","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ENDPOINT_DISABLED":{"summary":"ENDPOINT_DISABLED","value":{"type":"https://api.johku.com/problems/endpoint-disabled","status":503,"code":"ENDPOINT_DISABLED","title":"This endpoint is temporarily disabled"}}}}}}}}},"/v1/atlas/products/{id}":{"get":{"operationId":"getAtlasProduct","tags":["Atlas"],"summary":"One product, with descriptions, images and, for dates, availability and prices","parameters":[{"schema":{"type":"string","pattern":"^\\d{1,12}$","example":"48213","description":"The Atlas id"},"required":true,"description":"The Atlas id","name":"id","in":"path"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-24","description":"Arrival, or the first day of the range"},"required":false,"description":"Arrival, or the first day of the range","name":"start_date","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-24","description":"Departure, or the last day of the range"},"required":false,"description":"Departure, or the last day of the range","name":"end_date","in":"query"},{"schema":{"type":"integer","exclusiveMinimum":0,"maximum":1000},"required":false,"name":"participants","in":"query"},{"schema":{"type":"integer","exclusiveMinimum":0,"maximum":1000,"description":"Inventory units, e.g. cabins"},"required":false,"description":"Inventory units, e.g. cabins","name":"units","in":"query"}],"responses":{"200":{"description":"The product","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AtlasProduct"}}}},"400":{"description":"The request is not valid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"VALIDATION_FAILED":{"summary":"VALIDATION_FAILED","value":{"type":"https://api.johku.com/problems/validation-failed","status":400,"code":"VALIDATION_FAILED","title":"The request is not valid","errors":[{"path":"limit","code":"TOO_BIG","message":"Too big: expected number to be <=100"}]}}}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"INVALID_KEY":{"summary":"INVALID_KEY","value":{"type":"https://api.johku.com/problems/invalid-key","status":401,"code":"INVALID_KEY","title":"The API key is not valid"}}}}}},"403":{"description":"The key, integration or shop connection does not allow this","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"SCOPE_NOT_GRANTED":{"summary":"SCOPE_NOT_GRANTED","value":{"type":"https://api.johku.com/problems/scope-not-granted","status":403,"code":"SCOPE_NOT_GRANTED","title":"This shop has not granted orders:read","detail":"Send an access request for the scope."}}}}}},"404":{"description":"No such product, or no longer listed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"NOT_FOUND":{"summary":"NOT_FOUND","value":{"type":"https://api.johku.com/problems/not-found","status":404,"code":"NOT_FOUND","title":"Not found","detail":"No such product, or no longer listed"}}}}}},"429":{"description":"A rate limit was hit: see Retry-After and the RateLimit headers","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"RATE_LIMITED":{"summary":"RATE_LIMITED","value":{"type":"https://api.johku.com/problems/rate-limited","status":429,"code":"RATE_LIMITED","title":"Too many requests","detail":"Retry after 12 s."}}}}}},"502":{"description":"`ATLAS_ERROR`: Atlas did not answer as expected","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ATLAS_ERROR":{"summary":"ATLAS_ERROR","value":{"type":"https://api.johku.com/problems/atlas-error","title":"Atlas did not answer as expected","status":502,"code":"ATLAS_ERROR","detail":"Try again in a moment."}}}}}},"503":{"description":"The endpoint is disabled or busy","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ENDPOINT_DISABLED":{"summary":"ENDPOINT_DISABLED","value":{"type":"https://api.johku.com/problems/endpoint-disabled","status":503,"code":"ENDPOINT_DISABLED","title":"This endpoint is temporarily disabled"}}}}}}}}},"/v1/atlas/companies/{shop}":{"get":{"operationId":"getAtlasCompany","tags":["Atlas"],"summary":"A shop as a company: its details and listed products","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_]{1,64}$","example":"johkula","description":"The shop id (its subdomain on johku.com)"},"required":true,"description":"The shop id (its subdomain on johku.com)","name":"shop","in":"path"}],"responses":{"200":{"description":"The company","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AtlasCompany"}}}},"400":{"description":"The request is not valid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"VALIDATION_FAILED":{"summary":"VALIDATION_FAILED","value":{"type":"https://api.johku.com/problems/validation-failed","status":400,"code":"VALIDATION_FAILED","title":"The request is not valid","errors":[{"path":"limit","code":"TOO_BIG","message":"Too big: expected number to be <=100"}]}}}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"INVALID_KEY":{"summary":"INVALID_KEY","value":{"type":"https://api.johku.com/problems/invalid-key","status":401,"code":"INVALID_KEY","title":"The API key is not valid"}}}}}},"403":{"description":"The key, integration or shop connection does not allow this","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"SCOPE_NOT_GRANTED":{"summary":"SCOPE_NOT_GRANTED","value":{"type":"https://api.johku.com/problems/scope-not-granted","status":403,"code":"SCOPE_NOT_GRANTED","title":"This shop has not granted orders:read","detail":"Send an access request for the scope."}}}}}},"404":{"description":"No such shop, or not listed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"NOT_FOUND":{"summary":"NOT_FOUND","value":{"type":"https://api.johku.com/problems/not-found","status":404,"code":"NOT_FOUND","title":"Not found","detail":"No such shop, or not listed"}}}}}},"429":{"description":"A rate limit was hit: see Retry-After and the RateLimit headers","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"RATE_LIMITED":{"summary":"RATE_LIMITED","value":{"type":"https://api.johku.com/problems/rate-limited","status":429,"code":"RATE_LIMITED","title":"Too many requests","detail":"Retry after 12 s."}}}}}},"502":{"description":"`ATLAS_ERROR`: Atlas did not answer as expected","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ATLAS_ERROR":{"summary":"ATLAS_ERROR","value":{"type":"https://api.johku.com/problems/atlas-error","title":"Atlas did not answer as expected","status":502,"code":"ATLAS_ERROR","detail":"Try again in a moment."}}}}}},"503":{"description":"The endpoint is disabled or busy","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ENDPOINT_DISABLED":{"summary":"ENDPOINT_DISABLED","value":{"type":"https://api.johku.com/problems/endpoint-disabled","status":503,"code":"ENDPOINT_DISABLED","title":"This endpoint is temporarily disabled"}}}}}}}}},"/v1/atlas/product-types":{"get":{"operationId":"listAtlasProductTypes","tags":["Atlas"],"summary":"The product types the `types` filter takes","responses":{"200":{"description":"The types","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AtlasProductTypeList"}}}},"400":{"description":"The request is not valid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"VALIDATION_FAILED":{"summary":"VALIDATION_FAILED","value":{"type":"https://api.johku.com/problems/validation-failed","status":400,"code":"VALIDATION_FAILED","title":"The request is not valid","errors":[{"path":"limit","code":"TOO_BIG","message":"Too big: expected number to be <=100"}]}}}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"INVALID_KEY":{"summary":"INVALID_KEY","value":{"type":"https://api.johku.com/problems/invalid-key","status":401,"code":"INVALID_KEY","title":"The API key is not valid"}}}}}},"403":{"description":"The key, integration or shop connection does not allow this","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"SCOPE_NOT_GRANTED":{"summary":"SCOPE_NOT_GRANTED","value":{"type":"https://api.johku.com/problems/scope-not-granted","status":403,"code":"SCOPE_NOT_GRANTED","title":"This shop has not granted orders:read","detail":"Send an access request for the scope."}}}}}},"429":{"description":"A rate limit was hit: see Retry-After and the RateLimit headers","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"RATE_LIMITED":{"summary":"RATE_LIMITED","value":{"type":"https://api.johku.com/problems/rate-limited","status":429,"code":"RATE_LIMITED","title":"Too many requests","detail":"Retry after 12 s."}}}}}},"502":{"description":"`ATLAS_ERROR`: Atlas did not answer as expected","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ATLAS_ERROR":{"summary":"ATLAS_ERROR","value":{"type":"https://api.johku.com/problems/atlas-error","title":"Atlas did not answer as expected","status":502,"code":"ATLAS_ERROR","detail":"Try again in a moment."}}}}}},"503":{"description":"The endpoint is disabled or busy","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ENDPOINT_DISABLED":{"summary":"ENDPOINT_DISABLED","value":{"type":"https://api.johku.com/problems/endpoint-disabled","status":503,"code":"ENDPOINT_DISABLED","title":"This endpoint is temporarily disabled"}}}}}}}}},"/v1/atlas/proposals":{"post":{"operationId":"createAtlasProposal","tags":["Atlas"],"summary":"Private storefront pages for chosen products, one per shop","description":"For integrations that don't book themselves: each page shows the chosen products with their dates on the shop's storefront, and the customer books there. Nothing is held. Pages expire in 7 days.","parameters":[{"schema":{"type":"string","minLength":8,"maxLength":128,"example":"0b9f6c1e-3d0a-4c35-9b8e-2f3f1d6b7a10","description":"Retrying a POST with the same key within 24 hours returns the first result instead of acting twice"},"required":false,"description":"Retrying a POST with the same key within 24 hours returns the first result instead of acting twice","name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AtlasProposalInput"}}}},"responses":{"200":{"description":"The pages, and the products that couldn't be included","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AtlasProposal"}}}},"400":{"description":"The request is not valid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"VALIDATION_FAILED":{"summary":"VALIDATION_FAILED","value":{"type":"https://api.johku.com/problems/validation-failed","status":400,"code":"VALIDATION_FAILED","title":"The request is not valid","errors":[{"path":"limit","code":"TOO_BIG","message":"Too big: expected number to be <=100"}]}}}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"INVALID_KEY":{"summary":"INVALID_KEY","value":{"type":"https://api.johku.com/problems/invalid-key","status":401,"code":"INVALID_KEY","title":"The API key is not valid"}}}}}},"403":{"description":"The key, integration or shop connection does not allow this","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"SCOPE_NOT_GRANTED":{"summary":"SCOPE_NOT_GRANTED","value":{"type":"https://api.johku.com/problems/scope-not-granted","status":403,"code":"SCOPE_NOT_GRANTED","title":"This shop has not granted orders:read","detail":"Send an access request for the scope."}}}}}},"409":{"description":"`IDEMPOTENCY_IN_PROGRESS`: a request with this Idempotency-Key is still running; retry after `Retry-After`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"IDEMPOTENCY_IN_PROGRESS":{"summary":"IDEMPOTENCY_IN_PROGRESS","value":{"type":"https://api.johku.com/problems/idempotency-in-progress","title":"A request with this Idempotency-Key is still running","status":409,"code":"IDEMPOTENCY_IN_PROGRESS","detail":"Retry in a moment to get its result."}}}}}},"422":{"description":"`PROPOSAL_EMPTY`: none of the products can be put on a page. Or `IDEMPOTENCY_KEY_REUSED`: this Idempotency-Key was used for a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"PROPOSAL_EMPTY":{"summary":"PROPOSAL_EMPTY","value":{"type":"https://api.johku.com/problems/proposal-empty","title":"None of the products can be put on a page","status":422,"code":"PROPOSAL_EMPTY"}},"IDEMPOTENCY_KEY_REUSED":{"summary":"IDEMPOTENCY_KEY_REUSED","value":{"type":"https://api.johku.com/problems/idempotency-key-reused","title":"This Idempotency-Key was used for a different request","status":422,"code":"IDEMPOTENCY_KEY_REUSED","detail":"Use a new key for a new request."}}}}}},"429":{"description":"A rate limit was hit: see Retry-After and the RateLimit headers","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"RATE_LIMITED":{"summary":"RATE_LIMITED","value":{"type":"https://api.johku.com/problems/rate-limited","status":429,"code":"RATE_LIMITED","title":"Too many requests","detail":"Retry after 12 s."}}}}}},"502":{"description":"`ATLAS_ERROR`: Atlas did not answer as expected","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ATLAS_ERROR":{"summary":"ATLAS_ERROR","value":{"type":"https://api.johku.com/problems/atlas-error","title":"Atlas did not answer as expected","status":502,"code":"ATLAS_ERROR","detail":"Try again in a moment."}}}}}},"503":{"description":"The endpoint is disabled or busy","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ENDPOINT_DISABLED":{"summary":"ENDPOINT_DISABLED","value":{"type":"https://api.johku.com/problems/endpoint-disabled","status":503,"code":"ENDPOINT_DISABLED","title":"This endpoint is temporarily disabled"}}}}}}}}}},"webhooks":{}}