# Building an integration with the Johku Partner API

This guide is for developers and coding agents connecting a product to Johku: showing a shop's products,
checking availability and prices, booking, and reading orders and sales. The full contract, with every field, is
in the OpenAPI document; this guide explains how the pieces fit together.

- API: `https://api.johku.com/v1`
- Reference (try requests in the browser): https://api.johku.com/docs
- OpenAPI 3.1: https://api.johku.com/v1/openapi.json
- Index for agents: https://api.johku.com/llms.txt

Johku is a booking and sales platform for tourism and leisure businesses in Finland. Each business is a **shop** with
an id: its subdomain on johku.com (`johkula` for `johkula.johku.com`). Shops sell products of several kinds: things to buy,
rentals and stays by the day, activities by the hour, events with shows and seats, and transport with departures.

## 1. Access

Johku gives you a **partner** account, names its first **owner** and decides which APIs (scopes) the partner may
use. You manage the rest yourselves in Johku, signed in with your Johku account, under Settings → Partner integrations
→ Johku partners:

- **Owners** add and remove developers, create an **integration** for each product (its name and description are what
  the shops see), choose the scopes it may ask shops for from the partner's allowed APIs, create and revoke its API
  keys, and delete integrations.
- **Developers** see the partner's integrations and their usage, and create and revoke test keys.

API keys belong to the integration.

| Partner status | What you can do |
|---|---|
| `pending` | Test keys only, against the sandbox shop |
| `pilot` | Live keys, with a limited number of connected shops, while Johku reviews your first integration |
| `verified` | Live keys, any number of shops and integrations |

A shop's data is never available without the **shop's consent**. A shop connects your integration in Johku
(Settings → Integrations), choosing which of your integration's scopes it grants, or approves the access request
you send it. It can revoke the connection at any time; your calls to that shop then answer 403.

Shops take partner integrations with the **Johku Power** or **Johku Max** plan. When a shop's plan ends, its
connections are **paused**: calls answer 403 `SHOP_CONNECTION_PAUSED`, and `GET /v1/connections` shows them with
`status: paused`. They resume by themselves, with the same scopes, when the shop has the plan again.

```http
POST /v1/access-requests
{ "shop": "johkula", "scopes": ["catalog:read", "availability:read", "booking:write"], "reason": "Show your tours on Example Travel" }
```

`GET /v1/connections` lists the shops connected to your integration with their scopes, and `GET /v1/access-requests`
your requests. Both need a live secret key.

### Scopes

| Scope | Allows |
|---|---|
| `catalog:read` | The shop, its categories and products |
| `availability:read` | Booking options, availability, seat maps and quotes |
| `booking:write` | Carts and the checkout link (the customer pays in the shop's own checkout) |
| `booking:confirm` | Confirmed bookings paid outside Johku, for resellers. Shops grant this one separately |
| `orders:read` | Orders and reservations |
| `customers:read` | The customer register |
| `reports:read` | Sales reports |
| `atlas:read` | Johku Atlas, a search across all Johku shops. Granted by Johku to the integration, needs no shop connection |

## 2. Keys

Send the key in every request: `Authorization: Bearer <key>`.

| Key | Where it may be used |
|---|---|
| `jk_live_…`, `jk_test_…` (secret) | Your server only. Requests with a browser `Origin` header are refused (`SECRET_KEY_IN_BROWSER`) |
| `jk_pub_live_…`, `jk_pub_test_…` (publishable) | Browsers, only from the origins listed on the key, only for catalog, availability, carts and Atlas. Also limited per visitor IP |

- **Test keys** only reach the sandbox shop `johkula`, a demo shop with made-up products and orders. It needs no
  access request: every endpoint your integration's scopes allow works there, from the catalog to quotes, carts,
  bookings, orders and reports. Carts and bookings you make there are real orders in the demo shop.
- **Live keys** reach the shops that have connected your integration.
- Keys are shown once when created. Keep secret keys in your server's secret store, never in client code or a
  repository. Revoke a key you think has leaked at once under Johku partners (live keys: an owner).

`GET /v1/me` tells you which partner, integration and key a request runs as, and your limits.

## 3. Conventions

- **JSON** in and out. Field names are `snake_case`.
- **Shop ids** are letters, digits and `_`.
- **Money** is an object in minor units: `{ "amount": 2450, "currency": "EUR" }` is 24.50 €. Prices include VAT.
- **Dates** are `YYYY-MM-DD`; **times of day** are `HH:MM` in the shop's local time. Timestamps are ISO 8601 with
  an offset. Shops run on Finnish time (`Europe/Helsinki`).
- **Language:** `Accept-Language: en` (or `fi`, `sv`, `de`…) picks among the shop's languages; otherwise the
  shop's default.
- **Pagination:** lists answer `{ "data": [...], "next_cursor": "…" }`. Pass `cursor=<next_cursor>` for the next
  page; `null` means the last page. There is no total count. `limit` sets the page size.
- **Retries:** send an `Idempotency-Key` header (8–128 characters, e.g. a UUID) with every POST, and the same
  key when you retry it. Within 24 hours a retry gets the first answer back, marked `Idempotent-Replayed: true`,
  instead of acting twice. The same key with a different request answers 422 `IDEMPOTENCY_KEY_REUSED`; a retry
  while the first is still running answers 409 `IDEMPOTENCY_IN_PROGRESS` with `Retry-After`. Only answers that
  settle the request are kept (success, or a booking line the engine refused): after a 429 or 5xx the retry runs
  for real. Keys are per API key. Confirmed bookings are also deduplicated by your `reference`.

## 4. Errors

Errors are `application/problem+json` (RFC 9457) with a stable `code` to branch on:

```json
{
  "type": "https://api.johku.com/problems/shop-not-connected",
  "title": "This shop has not connected your integration",
  "status": 403,
  "code": "SHOP_NOT_CONNECTED",
  "detail": "Ask the shop to connect it, or send an access request (POST /v1/access-requests).",
  "instance": "/v1/shops/johkula/products"
}
```

| Status | Meaning | Common codes |
|---|---|---|
| 400 | The request doesn't match the schema; `errors[]` lists each field | `VALIDATION_FAILED`, `INVALID_CURSOR` |
| 401 | Missing or bad key | `UNAUTHENTICATED`, `INVALID_KEY`, `KEY_REVOKED`, `KEY_EXPIRED` |
| 403 | The key, integration or shop doesn't allow this | `SHOP_NOT_CONNECTED`, `SHOP_CONNECTION_PAUSED`, `SCOPE_NOT_GRANTED`, `TEST_KEY_LIVE_SHOP`, `SECRET_KEY_IN_BROWSER`, `ORIGIN_NOT_ALLOWED`, `LIVE_KEY_NOT_ALLOWED` |
| 404 | No such shop, product, order… | `NOT_FOUND` |
| 409 | The same `Idempotency-Key` or booking `reference` is still being handled: retry after `Retry-After`. Or the cart is in the shop's checkout and can't change | `IDEMPOTENCY_IN_PROGRESS`, `ORDERBUILD_LOCKED`, `CART_NOT_ON_HOLD` |
| 422 | The booking engine can't book a line as given (`errors[].line` points at the line), or an `Idempotency-Key` was reused for another request | the engine's code, e.g. `BOOKING_SEATS_REQUIRED`, `PRODUCT_NOT_FOUND`, `PRODUCT_NOT_BOOKABLE_VIA_API`; `IDEMPOTENCY_KEY_REUSED` |
| 429 | Rate limited: wait `Retry-After` seconds | `RATE_LIMITED`, `CONCURRENCY_LIMITED` |
| 502, 503 | The shop's backend or the endpoint is busy or disabled: retry after `Retry-After` | `BACKEND_ERROR`, `ENDPOINT_BUSY`, `ENDPOINT_DISABLED`, `TEMPORARILY_UNAVAILABLE` |

Every response has an `X-Request-Id`; include it when you contact Johku about a request.

## 5. Rate limits

Each key has a per-minute and a per-day quota, and each partner a cap on requests in flight at once. Endpoints
cost different amounts (a product read 1, availability 3, a report 10). Responses carry `RateLimit-Limit`,
`RateLimit-Remaining`, `RateLimit-Reset` and `RateLimit-Policy`. On 429 or 503, wait `Retry-After` seconds and
retry; don't retry faster. Cache catalog data on your side: products change rarely, and the API caches them for
about a minute anyway.

## 6. Reading a shop's catalog

```http
GET /v1/shops/johkula                      the shop: name, currency, languages, contacts
GET /v1/shops/johkula/categories           categories in storefront order
GET /v1/shops/johkula/products?q=sauna     search, or leave out q to list everything (category=<id> filters)
GET /v1/shops/johkula/products/259         one product
```

A product tells you how it is booked:
- `bookable_via_api`: whether the API can book it. When `false`, send the customer to `booking_url`, the
  product on the shop's own storefront, where every product can be booked.
- `booking_mode`: the line shape it needs (`buyable`, `days`, `hours`, `event` or `transport`).
- `price_tiers`: participant types such as adults and children, when the price depends on them.
- `from_price`: the lowest public price, `null` when the shop hides prices.

## 7. Booking

All prices, availability and rules are decided by Johku; never compute prices yourself. Every product type is booked
with the same calls; what differs is the fields of its booking line, and booking options tell you which.

### 7.1 The steps, in order

1. **Pick the product.** `GET …/products/{id}` (or an Atlas result). If `bookable_via_api` is `false`, stop here and
   send the customer to `booking_url`: the shop's own site books every product. Booking such a product answers 422
   `PRODUCT_NOT_BOOKABLE_VIA_API`.
2. **Learn its shape.** `GET …/products/{id}/booking-options` without a date gives `modes`, `price_tiers`,
   `rateplans`, `options`, `option_groups`, `packaged_products`, `form` and `hints`; also `free_dates` (by the day,
   by the hour, transport), `upcoming_shows` (events) or `routes` (transport).
3. **Pick a day.** Use `free_dates`, or `GET …/products/{id}/availability?from=&to=&participants=` for a calendar
   (up to 93 days). Events pick a show from `upcoming_shows` instead.
4. **Pick a time and the details for that day.** Ask booking options again with `date` and `participants` (and
   `origin` and `destination` for transport): it answers `times`, `checkin`, `shows` or `departures` for that day.
   Add `start_time` to also get `pickup_places` and the free places of each `pool_choice`. Ask again whenever the
   customer changes the date, time or number of people.
5. **Build the line** for the product's mode (7.3), then its options, packages and form answers (7.4).
6. **Quote it.** `POST …/quotes` prices the lines without holding anything. A 422 names the problem: `code` and
   `errors[].line` say which line and why. Fix the line and quote again. Show the customer the quoted total.
7. **Book it**, one of two ways:
   - The customer pays the shop (`booking:write`): `POST …/carts` holds the places for 30 minutes, and
     `POST …/carts/{id}/checkout` gives a one-time link to send the customer's browser to. They fill in their
     details and pay in the shop's checkout, then come back to your `return_url`. Poll `GET …/carts/{id}` until
     `status` is `ordered`, which gives `order_id` (7.6).
   - You collect the money yourself (`booking:confirm`, resellers): `POST …/bookings` with your `reference` and
     the customer makes a confirmed booking at once (7.7).

### 7.2 Booking options

```http
GET /v1/shops/johkula/products/259/booking-options?date=2026-12-24&participants=2
```

The answer describes what can be chosen for that product and date. **`hints`** says, in plain English, what this
product's line needs next; read it, it is written for this. `checked_for_participants` is the head count the free
places were checked for.

### 7.3 Lines: what each booking mode needs

A line is one thing to book. `booking_mode` (on the product) and `modes` (in booking options) say which shape the
line takes. A product with both `days` and `hours` is booked by the day when the line has `nights` or `end_date`,
otherwise by the hour.

| Mode | Required | Optional | Values from booking options |
|---|---|---|---|
| `buyable` | `product_id`, `count` | `resources` `{pool_id: resource_id}`: a variant (size, colour) from each `selectable` pool | `resource_pools` |
| `days` | `product_id`, `date`, `participants`; `nights` or `end_date` when `allow_multiday` | `start_time` and `end_time` (check-in and check-out), `rateplan_id`, `resources` | `free_dates`, `checkin.slots`, `rateplans` |
| `hours` | `product_id`, `date`, `start_time`, `end_time` or `duration` (minutes), `participants` | `rateplan_id`, `resources` | `free_dates`, `times.slots` |
| `event` | `product_id`, `show_id`, `participants` (or `tickets`) | `seat_ids`, **required** when the show has `seatmap: true` | `upcoming_shows` or `shows` (only `bookable` ones), `GET …/shows/{id}/seatmap` |
| `transport` | `product_id`, `date`, `origin`, `destination`, `start_time` (the departure), `participants` | `return` `{date, time}` | `routes` (stop ids), `departures.slots` |

On top of the mode:
- **`participants`** is a head count, or `{price_tier_id: count}` when booking options say `participant_pricing`
  (ids from `price_tiers`).
- **Ticket activities** (`ticket_activity: true`) take `tickets` `{ticket_product_id: count}` from `tickets`.
- **A choice per participant** (`pool_choice` is set, e.g. a bike size per rider): `resource_pools`, one choice id
  per participant, or a single id for everyone.
- **Rate plans**: leave `rateplan_id` out for the default plan.
- **Specific resources** (a room, a boat): `resources` `{pool_id: [resource_id]}`; otherwise Johku picks them.
- **Fixed dates**: some products are sold only on the dates their hints list.

```jsonc
// buyable
{ "product_id": 3, "count": 2 }
// days: a stay of three nights
{ "product_id": 1, "date": "2026-12-24", "nights": 3, "participants": 2 }
// hours, priced per participant type
{ "product_id": 6, "date": "2026-12-24", "start_time": "14:00", "duration": 120, "participants": { "12": 2, "13": 1 } }
// event: a show, with seats when the show has a seat map
{ "product_id": 40, "show_id": 9182, "participants": 2 }
{ "product_id": 40, "show_id": 9182, "seat_ids": [10192, 10193] }
// transport: from one stop to another on a departure, and back
{ "product_id": 77, "date": "2026-12-24", "origin": 5, "destination": 8, "start_time": "09:30", "participants": 2,
  "return": { "date": "2026-12-27", "time": "16:00" } }
```

Seats: `GET …/shows/{show_id}/seatmap` lists the venue's seats for that show, each with its position, row, number,
price zone and whether it's `available`. The map is live: ask again just before booking.

### 7.4 Options, packages, forms and discount codes

**Options** (`options` in booking options) go in the line's own `options` list, each a line of its own:
- `automatic: true`: the shop adds it; don't send it.
- `required: true`: you must send it. In an option group (`option_groups`) with `required: true`, send exactly one
  of its `product_ids`. A group never takes more than one.
- `needs` says what the option line needs besides `product_id`: a `count` (`count_selectable`), its own `date`,
  `start_time` and `end_time`, a `stop_id` from `pickup_places` (pick-up and drop-off places), or nothing.

**Packages** (`packaged_products`, with `packages_hint`): one `packages` entry per participant, each listing the
chosen packaged products. Choose exactly one of each group of included products; extras that aren't included take
a `count`; a packaged product with `resource_pools` (sizes) needs one of them.

**Forms** (`form`, also on options): answer in the line's `form_response` `{field title: answer}`. Required fields
need an answer, checkboxes take `"1"` or `"0"`, and selects one of their `options`.

**Discount codes**: a `{ "discount_code": "WINTER10" }` line applies to the lines before it.

```jsonc
{
  "lines": [
    {
      "product_id": 6, "date": "2026-12-24", "start_time": "14:00", "duration": 120, "participants": 2,
      "form_response": { "Allergies": "none", "I accept the safety rules": "1" },
      "options": [
        { "product_id": 135, "count": 2 },   // count_selectable
        { "product_id": 141, "stop_id": 12 } // a pick-up place
      ]
    },
    { "discount_code": "WINTER10" }
  ]
}
```

Up to 50 lines per request.

### 7.5 Quote

```http
POST /v1/shops/johkula/quotes
{ "lines": [ { "product_id": 6, "date": "2026-12-24", "start_time": "14:00", "duration": 120, "participants": 2 } ] }
```

The answer prices each line and gives the `total` and `warnings`; nothing is held. A line that can't be booked as
given answers 422 with the engine's code and the line's index. `PRODUCT_NOT_FOUND` means the line's product isn't
published.

### 7.6 Cart and checkout (customer pays the shop)

```http
POST /v1/shops/johkula/carts                   { "lines": [ … ] }           → { "id": "crt_…", "status": "active", "hold_until": "…", "total": … }
PUT  /v1/shops/johkula/carts/crt_…             { "lines": [ … ] }           replace all lines
POST /v1/shops/johkula/carts/crt_…/checkout    { "return_url": "https://example.com/thanks" }   → { "checkout_url": "…", "expires_at": "…" }
GET  /v1/shops/johkula/carts/crt_…             status: active, checkout, ordered (with order_id), released or expired
DELETE /v1/shops/johkula/carts/crt_…           delete the cart and everything it holds
```

- A cart **holds** its places for 30 minutes (`hold_until`). Delete carts you won't use: `DELETE` removes all of
  the cart's lines with the reservations, seats and stock they held, and the cart can't be used again. A cart left
  alone is deleted the same way when its hold ends.
- Send the customer's browser to `checkout_url`. The link works once, until `expires_at`. The shop's own checkout
  asks for the customer's details, its terms and the payment. Its confirmation page then sends the customer to your
  `return_url` after 10 seconds, or at once with a link.
- From the handoff on, the basket is the customer's: `PUT` and `DELETE` answer 409 `CART_NOT_ON_HOLD`.
- The order is attributed to your integration. Read it back with `GET …/carts/{id}` (`order_id`) or the orders API.

### 7.7 Confirmed bookings (resellers)

With `booking:confirm`, which a shop grants only to resellers it trusts, you create a confirmed booking that you
have already been paid for:

```http
POST /v1/shops/johkula/bookings
{
  "reference": "EX-100234",
  "customer": { "first_name": "Maija", "last_name": "Meikäläinen", "email": "maija@example.com", "phone": "+358401234567" },
  "lines": [ { "product_id": 1, "date": "2026-12-24", "nights": 3, "participants": 2 } ]
}
```

`reference` is your own booking id (printable ASCII, no spaces). Sending the same reference again returns the
existing booking instead of making a second one, so it is safe to retry.

## 8. Orders, reservations and reports

```http
GET /v1/shops/johkula/orders?updated_since=2026-11-01T00:00:00+02:00    orders changed since then, oldest change first
GET /v1/shops/johkula/orders/4389                                       one order with its lines and reservations
GET /v1/shops/johkula/reservations?from=2026-12-01&to=2026-12-31        reservations starting in a window (default 30 days, at most 93)
```

**Syncing orders:** keep the `updated_at` of the last order you processed, and ask again with
`updated_since=<that>`. Process each page in order and follow `next_cursor`. Orders made before change tracking
began have `updated_at: null`; `created_from` and `created_to` list orders by the day they were made.

**Checking a code a customer brings:** when your service gives access to something sold in the shop (a guided
tour app, digital content, a membership), the shop can send the customer a link to your service with the order's
code: a product message with `{orderidentifier}`, such as `https://your.service/start?c={orderidentifier}`, sent
when the order has been paid. When the customer opens the link, look the code up:

```http
POST /v1/shops/johkula/orders/lookup      { "code": "37f80c34229f338171d83559051b0bbe" }    → the order, or 404
```

The answer is the same as `GET …/orders/{id}`: check `status` (`paid`) and grant access from `lines` (product and
quantity). Keep the order `id` you granted access for, so a second visit with the same code grants nothing new, and
look the code up again later if a refund should end the access. Codes are 32 hex characters (on a payment plan's later
payments followed by `@` and a number); only someone who has the order's messages knows one.

**Reports** run in the background:

```http
POST /v1/shops/johkula/reports        { "type": "sales", "from": "2026-10-01", "to": "2026-10-31" }   → { "id": "…", "status": "queued" }
GET  /v1/shops/johkula/reports/{id}   poll every few seconds until status is done (or failed)
```

Types: `sales` and `channel_sales`. A report covers at most 366 days.

**Customers** (`customers:read`, which shops grant separately):

```http
GET /v1/shops/johkula/customers?q=virtanen     the register, searched by name, company, email or phone
GET /v1/shops/johkula/customers/1234           one customer
```

A customer has a `name` (one field, as the shop keeps it), `company`, `email`, `phone`, `address` and
`marketing_consent`. Each read of a single customer goes into the shop's audit log. Only use marketing consent as the
shop's customers gave it.

## 9. Johku Atlas: searching across shops

With `atlas:read`, search products across every Johku shop that lists them publicly, without a connection to each
shop:

```http
GET /v1/atlas/products?q=sauna&place=Rovaniemi&start_date=2026-12-24&end_date=2026-12-26&participants=2
GET /v1/atlas/products?types=accommodation&lat=60.17&lng=24.94&radius_km=30&sort=distance
GET /v1/atlas/product-types
GET /v1/atlas/products/{id}?start_date=…       one product, with availability and prices for the dates
GET /v1/atlas/companies/{shop}                 a shop with its listed products
POST /v1/atlas/proposals                       private storefront pages for chosen products, one per shop
```

Atlas prices are in cents. Each result has a `shop` and `product_id`: to book it through the API, use those with the
shop's own endpoints once the shop has connected your integration; otherwise send the customer to `booking_url`.

## 10. Trying requests in the reference

Open https://api.johku.com/docs, choose an operation, enter your key under Authentication and send a request.
- **Test keys** can do everything there, against the sandbox shop `johkula`.
- **Live keys** only read there (plus quotes, reports and order lookups). Carts, checkout links, bookings and access requests in
  live shops are made from your server; the reference answers `DOCS_LIVE_KEY_READ_ONLY`.
- The page doesn't store your key: it is gone when you close the tab. Don't try keys on a shared computer.

## 11. Checklist for a good integration

- Secret keys stay on your server. Browsers get a publishable key restricted to your site, or talk to your server.
- Handle `bookable_via_api: false` by linking to `booking_url`.
- Let booking options and their `hints` drive your booking form instead of hard-coding a product's rules.
- Quote before you hold, and delete carts you won't use.
- Branch on `code`, not on `title` or `detail`, which may be reworded.
- Send an `Idempotency-Key` with every POST and reuse it on retries.
- Honour `Retry-After` on 409, 429, 502 and 503, and cache catalog data.
- Expect 403 `SHOP_NOT_CONNECTED` at any time: shops can revoke access. `SHOP_CONNECTION_PAUSED` means the shop's
  plan ended; the connection comes back when the plan does.
- Show times in the shop's time zone, and money from minor units with the given currency.

## 12. SDKs

SDKs for JavaScript/TypeScript (`@johku/api`, and `@johku/booking` for a headless booking form), PHP 7.4+ including
WordPress (`johku/api`) and Python 3.9+ (`johku`) are coming. Until they are published, call the API over HTTP, or
generate a client from the OpenAPI document.
