Partner API Help

Choose the right flow

InquiryUse this for an open-ended or custom-tour question. The Partner API does not currently expose a general inquiry endpoint; contact API support to agree on an intake channel.

Booking requestPOST /booking-requests creates a pending request for SHT review. It never starts payment and is not a confirmed booking.

Booking / paymentPOST /bookings may return payment mode when enabled for your key. A booking is confirmed only when its returned status is confirmed.

Authentication

Send your key in every request. Keep it on your server and redact it from logs.

X-Api-Key: sht_YOUR_API_KEY

Placeholder only: sht_YOUR_API_KEY is not a real secret. Do not embed production keys in browsers, mobile apps, screenshots, or source control.

Complete booking-request example

POST `/booking-requests`

curl -X POST "https://YOUR-SHT-HOST/api/partner/v1/booking-requests" \
  -H "X-Api-Key: sht_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tourSlug": "gamla-stan-walking-tour",
    "preferredDate": "2026-10-15T00:00:00Z",
    "preferredTime": "10:00",
    "groupSize": 4,
    "customerName": "Example Customer",
    "customerEmail": "customer@example.com",
    "customerPhone": "+46 70 000 00 00",
    "pickupText": "Central Stockholm hotel",
    "preferredLanguage": "en",
    "customerNotes": "Vegetarian lunch requested; please confirm availability.",
    "externalReference": "RESELLER-2026-00421",
    "gdprConsent": true
  }'

Example response

{
  "bookingId": "9d40fd1c-4df3-46d0-a65f-5a91d78f279c",
  "partnerReference": "RESELLER-2026-00421",
  "status": "pending",
  "mode": "request",
  "totalPriceSEK": 1800,
  "partner": "Example Reseller",
  "channel": "partner:example"
}

Request fields

Field	Required	Meaning
`tourSlug`	Yes	Product/tour identifier from `GET /tours`.
`preferredDate`	Yes	ISO 8601 date/time. Check `GET /availability` first.
`customerName`, `customerEmail`	Yes	Lead passenger contact details.
`gdprConsent`	Yes	Must be `true`; your integration must have a valid basis for sharing the data.
`groupSize`	Recommended	Total passengers. Alternatively include `adultCount`, `youthCount`, and `childCount`.
`customerPhone`	Recommended	Include country code so operations can reach the customer.
`preferredTime`, `preferredLanguage`	No	Requested start time and language (`sv`, `en`, `de`, `fr`, or `es`).
`pickupPointId`, `pickupText`, `pickupAddress`	No	Use only when pickup applies to the selected tour.
`customerNotes`	No	Necessary operational notes or special requests only.
`externalReference`	Strongly recommended	Your stable, unique booking/request identifier.

Allergy, health, accessibility, and other special-needs details may be sensitive personal data. Send only what SHT needs to provide the service, avoid diagnoses or free-form medical histories, and ensure the customer has been properly informed.

Read status

GET `/bookings/{partnerReference}`

curl "https://YOUR-SHT-HOST/api/partner/v1/bookings/RESELLER-2026-00421" \
  -H "X-Api-Key: sht_YOUR_API_KEY"

Status / mode	Meaning
`pending`	Received; awaiting review or completion. Not confirmed.
`confirmed`	Confirmed by SHT.
`awaitingpayment` / mode `payment`	Payment is required. In payment mode the create response may include `checkoutUrl`.
`cancelled`	Cancelled (the equivalent of a rejected/withdrawn active request).
`lost`	Request was followed up but did not become a booking.
`completed`, `refunded`	Post-tour or refund states.
mode `request` / `quote`	Manual handling or quotation is required; poll the status endpoint at a reasonable interval.

Retries, idempotency, and reference IDs

Generate one unique externalReference for the business transaction and reuse it across retries. The current v1 create endpoint stores the reference for lookup but does not guarantee idempotent creation.

After a timeout or uncertain response, call GET /bookings/{externalReference}.
If found, use that booking instead of posting again.
Retry creation only when lookup returns 404, and serialize retries in your own system to reduce duplicate risk.

Common errors

HTTP	Cause / action
`400`	Missing/invalid fields, no GDPR consent, unavailable tour, invalid pax/capacity, or an update not allowed in the current state. Read the JSON `error`.
`401`	Missing, invalid, or inactive `X-Api-Key`.
`403`	The key is not allowed to access that tour.
`404`	Tour or partner-owned booking reference was not found.
`429`	Hourly quota exceeded. Back off until the next quota window; do not retry in a tight loop.
`5xx`	Temporary server failure. Use bounded exponential backoff and perform the reference lookup before retrying a create call.

{ "error": "Rate limit exceeded for this API key." }

Environment, limits, and privacy

API keys, allowed tours, payment permission, channel, and hourly quota are configured per partner. The default quota is 100 requests/hour, but your issued key's agreement is authoritative.
A public sandbox is not currently advertised. Ask API support for test access and the correct base URL before certification.
The partner is responsible for an appropriate legal basis, privacy notice, data accuracy, and secure handling when customer personal data is sent to SHT.
Do not send payment card data, passwords, government identifiers, or unrelated sensitive information.

Integration support and API-key requests: info@swedenhistorytours.se.

Choose the right flow

Authentication

Complete booking-request example

POST /booking-requests

Example response

Request fields

Read status

GET /bookings/{partnerReference}

Retries, idempotency, and reference IDs

Common errors

Environment, limits, and privacy

POST `/booking-requests`

GET `/bookings/{partnerReference}`