{ "openapi": "3.1.0", "info": { "title": "Samba API Docs", "version": "1.0.0", "description": "Read your Samba workspace's experiences, departures, bookings and customers from your own\nsystems: sync sales into a CRM or spreadsheet, or show your catalogue and availability on\nyour own site.\n\n## Authentication\n\nCreate a key under **Settings \u2192 API keys** (Owners and Admins). Keys start with `smb_sk_`,\nare shown once, and give read access to the whole workspace \u2014 keep them server-side. Send\nthe key as a Bearer token:\n\n```\ncurl https:\/\/api.sambahq.com\/v1\/workspace \\\n -H \"Authorization: Bearer smb_sk_\u2026\"\n```\n\n## Tools\n\nEvery endpoint has request samples in curl, JavaScript, Python, PHP and more. To explore the\nAPI in Postman or Insomnia, import the OpenAPI document (**Download OpenAPI Document** above,\nor `https:\/\/api-docs.sambahq.com\/openapi.json`) and set your key as a Bearer token.\n\n## Conventions\n\n- **Ids** are opaque strings prefixed with their type: `bk_` booking, `cus_` customer,\n `dep_` departure, `exp_` experience, `pkg_` package, `ptype_` passenger type, `addon_` add-on,\n `par_` participant, `bkao_` booking add-on line, `ws_` workspace, `txn_` transaction,\n `breq_` booking request, `inv_` invoice or credit note, `task_` task, `tans_` task answer,\n `creq_` cancellation request, `dsc_` discount code, `inst_` instalment, `pick_` pickup point,\n `pol_` cancellation policy, `fld_` folder, `blk_` content block. Store them as strings and\n don't parse them. Bookings also carry a human-facing `reference` (`SMB-2026-000123`).\n- **Money** is an integer in minor units (cents) with an ISO 4217 `currency`:\n `\"total_amount\": 12000, \"currency\": \"EUR\"` is \u20ac120.00.\n- **Timestamps** are ISO 8601 in UTC (`2026-10-02T09:30:00Z`). Departures also return the\n workspace `timezone`.\n- **Languages**: translatable text comes back in the workspace's default language; pass\n `?lang=fr` (any enabled language, see `GET \/workspace`) for another.\n- **Files**: `pdf_url` (invoices) and `file.url` (task answers) are API URLs. Download them\n with the same `Authorization: Bearer` header; they do not expire.\n- **Sensitive data**: task answers can contain passport numbers and health information. Any\n key can read them, so store and share them accordingly.\n- **Content blocks**: `content_blocks[].data` depends on the block `type`. Fields are only\n ever added to a type, never removed.\n\n## Pagination\n\nLists are cursor-paginated: `limit` (1\u2013100, default 50), then follow `links.next` \u2014 or pass\n`meta.next_cursor` as `cursor` \u2014 until it is null.\n\n## Keeping in sync\n\nEvery list accepts `updated_since`. Store the latest `updated_at` you have seen and ask for\neverything since; results are ordered by `updated_at`, then `id`, and the bound is\ninclusive, so de-duplicate by `id`. A booking's `updated_at` moves when the booking, a\nparticipant, an add-on line or a payment changes.\n\nTwo things `updated_since` does not cover:\n\n- **Live departure fields** \u2014 `seats_remaining`, `bookable` and `price_range` change with\n time (expiring checkout holds, booking cutoffs, date-based pricing) without a write. For\n availability, re-read a window of departures (`starts_after` \/ `starts_before`) on your own\n schedule.\n- **Discount code `status`** moves from `future` to `active` to `expired` as dates pass.\n Derive it from `starts_at`, `expires_at`, `max_redemptions` and `archived_at` if you cache\n codes.\n- **Snapshots**: the customer embedded in a booking or booking request, a booking's discount\n `code`, and the `task` summary on a task answer are copies. Sync the originals through\n `\/customers`, `\/discount-codes` and `\/tasks`.\n\n## Rate limits\n\n120 requests per minute per key. Responses carry `X-RateLimit-Limit` and\n`X-RateLimit-Remaining`; over the limit you get `429` with a `Retry-After` header.\n\n## Errors\n\nErrors share one shape:\n\n```json\n{ \"error\": { \"type\": \"invalid_request\", \"code\": \"invalid_filter\", \"message\": \"\u2026\", \"errors\": { \"status\": [\"\u2026\"] } } }\n```\n\n| Status | `code` |\n|---|---|\n| 401 | `invalid_api_key` |\n| 403 | `workspace_suspended` |\n| 404 | `not_found` |\n| 422 | `invalid_filter` |\n| 429 | `rate_limited` |\n| 500 | `server_error` |" }, "servers": [ { "url": "https:\/\/api.sambahq.com\/v1" } ], "security": [ { "http": [] } ], "paths": { "\/booking-requests": { "get": { "operationId": "v1.booking-requests.index", "description": "Private-tour and on-request bookings awaiting (or past) the operator's decision. An\naccepted request links to the booking it created.", "summary": "List booking requests", "tags": [ "Booking requests" ], "parameters": [ { "name": "lang", "in": "query", "description": "Language for translatable text (titles, descriptions, package and add-on names):\none of the workspace's enabled languages, e.g. `fr`. Defaults to the workspace's\ndefault language; an unknown or disabled language falls back to it too.", "schema": { "type": [ "string", "null" ], "maxLength": 10 }, "example": "fr" }, { "name": "limit", "in": "query", "description": "Number of records per page, 1 to 100.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from `meta.next_cursor` (or `links.next`) of the previous page.", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "description": "Only records whose stored data changed at or after this moment (ISO 8601).\nResults are then ordered by `updated_at`, then `id`, so you can store the\nlast `updated_at` you saw and ask for everything since.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-01T00:00:00Z" }, { "name": "status", "in": "query", "schema": { "$ref": "#\/components\/schemas\/BookingRequestStatus" } }, { "name": "experience_id", "in": "query", "description": "Only requests for this experience.", "schema": { "type": "string" }, "example": "exp_eUSX7jbEV9" }, { "name": "customer_id", "in": "query", "description": "Only requests from this customer.", "schema": { "type": "string" }, "example": "cus_MAmYDWY3Ku" } ], "responses": { "200": { "description": "Paginated set of `BookingRequestResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/BookingRequestResource" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/InvalidApiKey" }, "403": { "$ref": "#\/components\/responses\/WorkspaceSuspended" }, "422": { "$ref": "#\/components\/responses\/InvalidFilter" }, "429": { "$ref": "#\/components\/responses\/RateLimited" } } } }, "\/booking-requests\/{id}": { "get": { "operationId": "v1.booking-requests.show", "summary": "Get a booking request", "tags": [ "Booking requests" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The request's id, e.g. `breq_Lm3Vq8ZpTa`.", "schema": { "type": "string" } }, { "name": "lang", "in": "query", "description": "Language for translatable text (titles, descriptions, package and add-on names):\none of the workspace's enabled languages, e.g. `fr`. Defaults to the workspace's\ndefault language; an unknown or disabled language falls back to it too.", "schema": { "type": [ "string", "null" ], "maxLength": 10 }, "example": "fr" } ], "responses": { "200": { "description": "`BookingRequestResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/BookingRequestResource" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/InvalidApiKey" }, "403": { "$ref": "#\/components\/responses\/WorkspaceSuspended" }, "404": { "$ref": "#\/components\/responses\/NotFound" }, "422": { "$ref": "#\/components\/responses\/InvalidFilter" }, "429": { "$ref": "#\/components\/responses\/RateLimited" } } } }, "\/bookings": { "get": { "operationId": "v1.bookings.index", "description": "Bookings with their participants, add-ons and amounts. `updated_at` moves whenever the\nbooking, a participant, an add-on line or a payment changes, so `updated_since` is the\nway to keep a CRM or spreadsheet in sync.", "summary": "List bookings", "tags": [ "Bookings" ], "parameters": [ { "name": "lang", "in": "query", "description": "Language for translatable text (titles, descriptions, package and add-on names):\none of the workspace's enabled languages, e.g. `fr`. Defaults to the workspace's\ndefault language; an unknown or disabled language falls back to it too.", "schema": { "type": [ "string", "null" ], "maxLength": 10 }, "example": "fr" }, { "name": "limit", "in": "query", "description": "Number of records per page, 1 to 100.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from `meta.next_cursor` (or `links.next`) of the previous page.", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "description": "Only records whose stored data changed at or after this moment (ISO 8601).\nResults are then ordered by `updated_at`, then `id`, so you can store the\nlast `updated_at` you saw and ask for everything since.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-01T00:00:00Z" }, { "name": "status", "in": "query", "schema": { "$ref": "#\/components\/schemas\/BookingStatus" } }, { "name": "payment_status", "in": "query", "schema": { "$ref": "#\/components\/schemas\/BookingPaymentStatus" } }, { "name": "source", "in": "query", "schema": { "$ref": "#\/components\/schemas\/BookingSource" } }, { "name": "departure_id", "in": "query", "description": "Only bookings on this departure.", "schema": { "type": "string" }, "example": "dep_SGbSQzmJVG" }, { "name": "customer_id", "in": "query", "description": "Only bookings of this customer.", "schema": { "type": "string" }, "example": "cus_MAmYDWY3Ku" }, { "name": "reference", "in": "query", "description": "Exact booking reference, as shown to the customer.", "schema": { "type": "string", "maxLength": 64 } }, { "name": "created_since", "in": "query", "description": "Only bookings created at or after this moment (ISO 8601).", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-01T00:00:00Z" } ], "responses": { "200": { "description": "Paginated set of `BookingResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/BookingResource" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/InvalidApiKey" }, "403": { "$ref": "#\/components\/responses\/WorkspaceSuspended" }, "422": { "$ref": "#\/components\/responses\/InvalidFilter" }, "429": { "$ref": "#\/components\/responses\/RateLimited" } } } }, "\/bookings\/{id}": { "get": { "operationId": "v1.bookings.show", "summary": "Get a booking", "tags": [ "Bookings" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The booking's id, e.g. `bk_5odpWrSW5L`.", "schema": { "type": "string" } }, { "name": "lang", "in": "query", "description": "Language for translatable text (titles, descriptions, package and add-on names):\none of the workspace's enabled languages, e.g. `fr`. Defaults to the workspace's\ndefault language; an unknown or disabled language falls back to it too.", "schema": { "type": [ "string", "null" ], "maxLength": 10 }, "example": "fr" } ], "responses": { "200": { "description": "`BookingResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/BookingResource" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/InvalidApiKey" }, "403": { "$ref": "#\/components\/responses\/WorkspaceSuspended" }, "404": { "$ref": "#\/components\/responses\/NotFound" }, "422": { "$ref": "#\/components\/responses\/InvalidFilter" }, "429": { "$ref": "#\/components\/responses\/RateLimited" } } } }, "\/cancellation-requests": { "get": { "operationId": "v1.cancellation-requests.index", "description": "Travelers' requests to cancel, with the refund asked for, suggested by your policy and\nactually sent.", "summary": "List cancellation requests", "tags": [ "Cancellation requests" ], "parameters": [ { "name": "lang", "in": "query", "description": "Language for translatable text (titles, descriptions, package and add-on names):\none of the workspace's enabled languages, e.g. `fr`. Defaults to the workspace's\ndefault language; an unknown or disabled language falls back to it too.", "schema": { "type": [ "string", "null" ], "maxLength": 10 }, "example": "fr" }, { "name": "limit", "in": "query", "description": "Number of records per page, 1 to 100.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from `meta.next_cursor` (or `links.next`) of the previous page.", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "description": "Only records whose stored data changed at or after this moment (ISO 8601).\nResults are then ordered by `updated_at`, then `id`, so you can store the\nlast `updated_at` you saw and ask for everything since.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-01T00:00:00Z" }, { "name": "status", "in": "query", "schema": { "$ref": "#\/components\/schemas\/CancellationRequestStatus" } }, { "name": "booking_id", "in": "query", "description": "Only the request on this booking.", "schema": { "type": "string" }, "example": "bk_5odpWrSW5L" } ], "responses": { "200": { "description": "Paginated set of `CancellationRequestResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/CancellationRequestResource" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/InvalidApiKey" }, "403": { "$ref": "#\/components\/responses\/WorkspaceSuspended" }, "422": { "$ref": "#\/components\/responses\/InvalidFilter" }, "429": { "$ref": "#\/components\/responses\/RateLimited" } } } }, "\/cancellation-requests\/{id}": { "get": { "operationId": "v1.cancellation-requests.show", "summary": "Get a cancellation request", "tags": [ "Cancellation requests" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The request's id, e.g. `creq_KdHq2LmVa8`.", "schema": { "type": "string" } }, { "name": "lang", "in": "query", "description": "Language for translatable text (titles, descriptions, package and add-on names):\none of the workspace's enabled languages, e.g. `fr`. Defaults to the workspace's\ndefault language; an unknown or disabled language falls back to it too.", "schema": { "type": [ "string", "null" ], "maxLength": 10 }, "example": "fr" } ], "responses": { "200": { "description": "`CancellationRequestResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/CancellationRequestResource" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/InvalidApiKey" }, "403": { "$ref": "#\/components\/responses\/WorkspaceSuspended" }, "404": { "$ref": "#\/components\/responses\/NotFound" }, "422": { "$ref": "#\/components\/responses\/InvalidFilter" }, "429": { "$ref": "#\/components\/responses\/RateLimited" } } } }, "\/customers": { "get": { "operationId": "v1.customers.index", "description": "Includes anonymized customers (personal fields null, `anonymized: true`) so a sync can\nerase its own copy.", "summary": "List customers", "tags": [ "Customers" ], "parameters": [ { "name": "lang", "in": "query", "description": "Language for translatable text (titles, descriptions, package and add-on names):\none of the workspace's enabled languages, e.g. `fr`. Defaults to the workspace's\ndefault language; an unknown or disabled language falls back to it too.", "schema": { "type": [ "string", "null" ], "maxLength": 10 }, "example": "fr" }, { "name": "limit", "in": "query", "description": "Number of records per page, 1 to 100.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from `meta.next_cursor` (or `links.next`) of the previous page.", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "description": "Only records whose stored data changed at or after this moment (ISO 8601).\nResults are then ordered by `updated_at`, then `id`, so you can store the\nlast `updated_at` you saw and ask for everything since.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-01T00:00:00Z" }, { "name": "email", "in": "query", "description": "Exact email address (case-insensitive).", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Paginated set of `CustomerResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/CustomerResource" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/InvalidApiKey" }, "403": { "$ref": "#\/components\/responses\/WorkspaceSuspended" }, "422": { "$ref": "#\/components\/responses\/InvalidFilter" }, "429": { "$ref": "#\/components\/responses\/RateLimited" } } } }, "\/customers\/{id}": { "get": { "operationId": "v1.customers.show", "summary": "Get a customer", "tags": [ "Customers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The customer's id, e.g. `cus_MAmYDWY3Ku`.", "schema": { "type": "string" } }, { "name": "lang", "in": "query", "description": "Language for translatable text (titles, descriptions, package and add-on names):\none of the workspace's enabled languages, e.g. `fr`. Defaults to the workspace's\ndefault language; an unknown or disabled language falls back to it too.", "schema": { "type": [ "string", "null" ], "maxLength": 10 }, "example": "fr" } ], "responses": { "200": { "description": "`CustomerResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/CustomerResource" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/InvalidApiKey" }, "403": { "$ref": "#\/components\/responses\/WorkspaceSuspended" }, "404": { "$ref": "#\/components\/responses\/NotFound" }, "422": { "$ref": "#\/components\/responses\/InvalidFilter" }, "429": { "$ref": "#\/components\/responses\/RateLimited" } } } }, "\/departures": { "get": { "operationId": "v1.departures.index", "description": "For availability, read a window of departures (`starts_after` \/ `starts_before`) on your\nown schedule: `seats_remaining`, `bookable` and `price_range` are live fields that can\nchange without `updated_at` moving.", "summary": "List departures", "tags": [ "Departures" ], "parameters": [ { "name": "lang", "in": "query", "description": "Language for translatable text (titles, descriptions, package and add-on names):\none of the workspace's enabled languages, e.g. `fr`. Defaults to the workspace's\ndefault language; an unknown or disabled language falls back to it too.", "schema": { "type": [ "string", "null" ], "maxLength": 10 }, "example": "fr" }, { "name": "limit", "in": "query", "description": "Number of records per page, 1 to 100.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from `meta.next_cursor` (or `links.next`) of the previous page.", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "description": "Only records whose stored data changed at or after this moment (ISO 8601).\nResults are then ordered by `updated_at`, then `id`, so you can store the\nlast `updated_at` you saw and ask for everything since.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-01T00:00:00Z" }, { "name": "experience_id", "in": "query", "description": "Only departures of this experience.", "schema": { "type": "string" }, "example": "exp_eUSX7jbEV9" }, { "name": "status", "in": "query", "schema": { "$ref": "#\/components\/schemas\/DepartureStatus" } }, { "name": "starts_after", "in": "query", "description": "Only departures starting at or after this moment (ISO 8601).", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-01T00:00:00Z" }, { "name": "starts_before", "in": "query", "description": "Only departures starting before this moment (ISO 8601).", "schema": { "type": "string", "format": "date-time" }, "example": "2026-12-31T23:59:59Z" } ], "responses": { "200": { "description": "Paginated set of `DepartureResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/DepartureResource" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/InvalidApiKey" }, "403": { "$ref": "#\/components\/responses\/WorkspaceSuspended" }, "422": { "$ref": "#\/components\/responses\/InvalidFilter" }, "429": { "$ref": "#\/components\/responses\/RateLimited" } } } }, "\/departures\/{id}": { "get": { "operationId": "v1.departures.show", "summary": "Get a departure", "tags": [ "Departures" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The departure's id, e.g. `dep_SGbSQzmJVG`.", "schema": { "type": "string" } }, { "name": "lang", "in": "query", "description": "Language for translatable text (titles, descriptions, package and add-on names):\none of the workspace's enabled languages, e.g. `fr`. Defaults to the workspace's\ndefault language; an unknown or disabled language falls back to it too.", "schema": { "type": [ "string", "null" ], "maxLength": 10 }, "example": "fr" } ], "responses": { "200": { "description": "`DepartureResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/DepartureResource" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/InvalidApiKey" }, "403": { "$ref": "#\/components\/responses\/WorkspaceSuspended" }, "404": { "$ref": "#\/components\/responses\/NotFound" }, "422": { "$ref": "#\/components\/responses\/InvalidFilter" }, "429": { "$ref": "#\/components\/responses\/RateLimited" } } } }, "\/discount-codes": { "get": { "operationId": "v1.discount-codes.index", "description": "Promo codes with their value, limits and redemptions, for marketing attribution.", "summary": "List discount codes", "tags": [ "Discount codes" ], "parameters": [ { "name": "lang", "in": "query", "description": "Language for translatable text (titles, descriptions, package and add-on names):\none of the workspace's enabled languages, e.g. `fr`. Defaults to the workspace's\ndefault language; an unknown or disabled language falls back to it too.", "schema": { "type": [ "string", "null" ], "maxLength": 10 }, "example": "fr" }, { "name": "limit", "in": "query", "description": "Number of records per page, 1 to 100.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from `meta.next_cursor` (or `links.next`) of the previous page.", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "description": "Only records whose stored data changed at or after this moment (ISO 8601).\nResults are then ordered by `updated_at`, then `id`, so you can store the\nlast `updated_at` you saw and ask for everything since.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-01T00:00:00Z" }, { "name": "status", "in": "query", "description": "Status at the time of the request (see the `status` field).", "schema": { "$ref": "#\/components\/schemas\/DiscountCodeStatus" } }, { "name": "experience_id", "in": "query", "description": "Only codes limited to this experience.", "schema": { "type": "string" }, "example": "exp_eUSX7jbEV9" }, { "name": "code", "in": "query", "description": "Exact code, case-insensitive.", "schema": { "type": "string", "maxLength": 64 }, "example": "SUMMER26" } ], "responses": { "200": { "description": "Paginated set of `DiscountCodeResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/DiscountCodeResource" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/InvalidApiKey" }, "403": { "$ref": "#\/components\/responses\/WorkspaceSuspended" }, "422": { "$ref": "#\/components\/responses\/InvalidFilter" }, "429": { "$ref": "#\/components\/responses\/RateLimited" } } } }, "\/discount-codes\/{id}": { "get": { "operationId": "v1.discount-codes.show", "summary": "Get a discount code", "tags": [ "Discount codes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The code's id, e.g. `dsc_2LmVa8KdHq`.", "schema": { "type": "string" } }, { "name": "lang", "in": "query", "description": "Language for translatable text (titles, descriptions, package and add-on names):\none of the workspace's enabled languages, e.g. `fr`. Defaults to the workspace's\ndefault language; an unknown or disabled language falls back to it too.", "schema": { "type": [ "string", "null" ], "maxLength": 10 }, "example": "fr" } ], "responses": { "200": { "description": "`DiscountCodeResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/DiscountCodeResource" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/InvalidApiKey" }, "403": { "$ref": "#\/components\/responses\/WorkspaceSuspended" }, "404": { "$ref": "#\/components\/responses\/NotFound" }, "422": { "$ref": "#\/components\/responses\/InvalidFilter" }, "429": { "$ref": "#\/components\/responses\/RateLimited" } } } }, "\/experiences": { "get": { "operationId": "v1.experiences.index", "description": "Drafts, published and archived experiences, with their packages, passenger types and add-ons.", "summary": "List experiences", "tags": [ "Experiences" ], "parameters": [ { "name": "lang", "in": "query", "description": "Language for translatable text (titles, descriptions, package and add-on names):\none of the workspace's enabled languages, e.g. `fr`. Defaults to the workspace's\ndefault language; an unknown or disabled language falls back to it too.", "schema": { "type": [ "string", "null" ], "maxLength": 10 }, "example": "fr" }, { "name": "limit", "in": "query", "description": "Number of records per page, 1 to 100.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from `meta.next_cursor` (or `links.next`) of the previous page.", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "description": "Only records whose stored data changed at or after this moment (ISO 8601).\nResults are then ordered by `updated_at`, then `id`, so you can store the\nlast `updated_at` you saw and ask for everything since.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-01T00:00:00Z" }, { "name": "status", "in": "query", "schema": { "$ref": "#\/components\/schemas\/ExperienceStatus" } }, { "name": "type", "in": "query", "schema": { "$ref": "#\/components\/schemas\/ExperienceType" } } ], "responses": { "200": { "description": "Paginated set of `ExperienceResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/ExperienceResource" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/InvalidApiKey" }, "403": { "$ref": "#\/components\/responses\/WorkspaceSuspended" }, "422": { "$ref": "#\/components\/responses\/InvalidFilter" }, "429": { "$ref": "#\/components\/responses\/RateLimited" } } } }, "\/experiences\/{id}": { "get": { "operationId": "v1.experiences.show", "summary": "Get an experience", "tags": [ "Experiences" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The experience's id, e.g. `exp_eUSX7jbEV9`.", "schema": { "type": "string" } }, { "name": "lang", "in": "query", "description": "Language for translatable text (titles, descriptions, package and add-on names):\none of the workspace's enabled languages, e.g. `fr`. Defaults to the workspace's\ndefault language; an unknown or disabled language falls back to it too.", "schema": { "type": [ "string", "null" ], "maxLength": 10 }, "example": "fr" } ], "responses": { "200": { "description": "`ExperienceResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/ExperienceResource" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/InvalidApiKey" }, "403": { "$ref": "#\/components\/responses\/WorkspaceSuspended" }, "404": { "$ref": "#\/components\/responses\/NotFound" }, "422": { "$ref": "#\/components\/responses\/InvalidFilter" }, "429": { "$ref": "#\/components\/responses\/RateLimited" } } } }, "\/invoices": { "get": { "operationId": "v1.invoices.index", "description": "Every invoice and credit note issued for your bookings, with lines, VAT and the payments\napplied to it.", "summary": "List invoices and credit notes", "tags": [ "Invoices" ], "parameters": [ { "name": "lang", "in": "query", "description": "Language for translatable text (titles, descriptions, package and add-on names):\none of the workspace's enabled languages, e.g. `fr`. Defaults to the workspace's\ndefault language; an unknown or disabled language falls back to it too.", "schema": { "type": [ "string", "null" ], "maxLength": 10 }, "example": "fr" }, { "name": "limit", "in": "query", "description": "Number of records per page, 1 to 100.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from `meta.next_cursor` (or `links.next`) of the previous page.", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "description": "Only records whose stored data changed at or after this moment (ISO 8601).\nResults are then ordered by `updated_at`, then `id`, so you can store the\nlast `updated_at` you saw and ask for everything since.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-01T00:00:00Z" }, { "name": "kind", "in": "query", "schema": { "$ref": "#\/components\/schemas\/InvoiceKind" } }, { "name": "status", "in": "query", "schema": { "$ref": "#\/components\/schemas\/InvoiceStatus" } }, { "name": "booking_id", "in": "query", "description": "Only invoices and credit notes of this booking.", "schema": { "type": "string" }, "example": "bk_5odpWrSW5L" }, { "name": "issued_after", "in": "query", "description": "Only documents issued at or after this moment (ISO 8601).", "schema": { "type": "string", "format": "date-time" }, "example": "2026-09-01T00:00:00Z" }, { "name": "issued_before", "in": "query", "description": "Only documents issued at or before this moment (ISO 8601).", "schema": { "type": "string", "format": "date-time" }, "example": "2026-09-30T23:59:59Z" } ], "responses": { "200": { "description": "Paginated set of `InvoiceResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/InvoiceResource" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/InvalidApiKey" }, "403": { "$ref": "#\/components\/responses\/WorkspaceSuspended" }, "422": { "$ref": "#\/components\/responses\/InvalidFilter" }, "429": { "$ref": "#\/components\/responses\/RateLimited" } } } }, "\/invoices\/{id}": { "get": { "operationId": "v1.invoices.show", "summary": "Get an invoice or credit note", "tags": [ "Invoices" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The document's id, e.g. `inv_8KdPq2LmVa`.", "schema": { "type": "string" } }, { "name": "lang", "in": "query", "description": "Language for translatable text (titles, descriptions, package and add-on names):\none of the workspace's enabled languages, e.g. `fr`. Defaults to the workspace's\ndefault language; an unknown or disabled language falls back to it too.", "schema": { "type": [ "string", "null" ], "maxLength": 10 }, "example": "fr" } ], "responses": { "200": { "description": "`InvoiceResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/InvoiceResource" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/InvalidApiKey" }, "403": { "$ref": "#\/components\/responses\/WorkspaceSuspended" }, "404": { "$ref": "#\/components\/responses\/NotFound" }, "422": { "$ref": "#\/components\/responses\/InvalidFilter" }, "429": { "$ref": "#\/components\/responses\/RateLimited" } } } }, "\/invoices\/{id}\/pdf": { "get": { "operationId": "v1.invoices.pdf", "description": "The invoice or credit note as a PDF file (`application\/pdf`).", "summary": "Download an invoice PDF", "tags": [ "Invoices" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The document's id, e.g. `inv_8KdPq2LmVa`.", "schema": { "type": "string" } }, { "name": "lang", "in": "query", "description": "Language for translatable text (titles, descriptions, package and add-on names):\none of the workspace's enabled languages, e.g. `fr`. Defaults to the workspace's\ndefault language; an unknown or disabled language falls back to it too.", "schema": { "type": [ "string", "null" ], "maxLength": 10 }, "example": "fr" } ], "responses": { "200": { "description": "", "content": { "application\/pdf": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "Transfer-Encoding": { "required": true, "schema": { "type": "string", "enum": [ "chunked" ] } } } }, "401": { "$ref": "#\/components\/responses\/InvalidApiKey" }, "403": { "$ref": "#\/components\/responses\/WorkspaceSuspended" }, "404": { "$ref": "#\/components\/responses\/NotFound" }, "422": { "$ref": "#\/components\/responses\/InvalidFilter" }, "429": { "$ref": "#\/components\/responses\/RateLimited" } } } }, "\/task-answers": { "get": { "operationId": "v1.task-answers.index", "description": "Travelers' answers to your tasks, per participant or per booking. Answers can hold\nsensitive personal data (passport numbers, health information): store them accordingly.", "summary": "List task answers", "tags": [ "Task answers" ], "parameters": [ { "name": "lang", "in": "query", "description": "Language for translatable text (titles, descriptions, package and add-on names):\none of the workspace's enabled languages, e.g. `fr`. Defaults to the workspace's\ndefault language; an unknown or disabled language falls back to it too.", "schema": { "type": [ "string", "null" ], "maxLength": 10 }, "example": "fr" }, { "name": "limit", "in": "query", "description": "Number of records per page, 1 to 100.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from `meta.next_cursor` (or `links.next`) of the previous page.", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "description": "Only records whose stored data changed at or after this moment (ISO 8601).\nResults are then ordered by `updated_at`, then `id`, so you can store the\nlast `updated_at` you saw and ask for everything since.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-01T00:00:00Z" }, { "name": "booking_id", "in": "query", "description": "Only answers on this booking: the buyer's and every participant's.", "schema": { "type": "string" }, "example": "bk_5odpWrSW5L" }, { "name": "participant_id", "in": "query", "description": "Only this participant's answers.", "schema": { "type": "string" }, "example": "par_2LmVa8KdHq" }, { "name": "task_id", "in": "query", "description": "Only answers to this task.", "schema": { "type": "string" }, "example": "task_Hq2LmVa8Kd" }, { "name": "completed", "in": "query", "description": "`true`: answered. `false`: still waiting for an answer.", "schema": { "type": "boolean" }, "example": true } ], "responses": { "200": { "description": "Paginated set of `TaskAnswerResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/TaskAnswerResource" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/InvalidApiKey" }, "403": { "$ref": "#\/components\/responses\/WorkspaceSuspended" }, "422": { "$ref": "#\/components\/responses\/InvalidFilter" }, "429": { "$ref": "#\/components\/responses\/RateLimited" } } } }, "\/task-answers\/{id}": { "get": { "operationId": "v1.task-answers.show", "summary": "Get a task answer", "tags": [ "Task answers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The answer's id, e.g. `tans_Va8KdHq2Lm`.", "schema": { "type": "string" } }, { "name": "lang", "in": "query", "description": "Language for translatable text (titles, descriptions, package and add-on names):\none of the workspace's enabled languages, e.g. `fr`. Defaults to the workspace's\ndefault language; an unknown or disabled language falls back to it too.", "schema": { "type": [ "string", "null" ], "maxLength": 10 }, "example": "fr" } ], "responses": { "200": { "description": "`TaskAnswerResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/TaskAnswerResource" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/InvalidApiKey" }, "403": { "$ref": "#\/components\/responses\/WorkspaceSuspended" }, "404": { "$ref": "#\/components\/responses\/NotFound" }, "422": { "$ref": "#\/components\/responses\/InvalidFilter" }, "429": { "$ref": "#\/components\/responses\/RateLimited" } } } }, "\/task-answers\/{id}\/file": { "get": { "operationId": "v1.task-answers.file", "description": "The file a traveler uploaded for a `file` task.", "summary": "Download a task answer's file", "tags": [ "Task answers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The answer's id, e.g. `tans_Va8KdHq2Lm`.", "schema": { "type": "string" } }, { "name": "lang", "in": "query", "description": "Language for translatable text (titles, descriptions, package and add-on names):\none of the workspace's enabled languages, e.g. `fr`. Defaults to the workspace's\ndefault language; an unknown or disabled language falls back to it too.", "schema": { "type": [ "string", "null" ], "maxLength": 10 }, "example": "fr" } ], "responses": { "200": { "description": "", "content": { "application\/octet-stream": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "Transfer-Encoding": { "required": true, "schema": { "type": "string", "enum": [ "chunked" ] } } } }, "401": { "$ref": "#\/components\/responses\/InvalidApiKey" }, "403": { "$ref": "#\/components\/responses\/WorkspaceSuspended" }, "404": { "$ref": "#\/components\/responses\/NotFound" }, "422": { "$ref": "#\/components\/responses\/InvalidFilter" }, "429": { "$ref": "#\/components\/responses\/RateLimited" } } } }, "\/tasks": { "get": { "operationId": "v1.tasks.index", "description": "The forms travelers fill in (passport details, dietary needs, waivers\u2026). Answers are under\n`\/task-answers`.", "summary": "List tasks", "tags": [ "Tasks" ], "parameters": [ { "name": "lang", "in": "query", "description": "Language for translatable text (titles, descriptions, package and add-on names):\none of the workspace's enabled languages, e.g. `fr`. Defaults to the workspace's\ndefault language; an unknown or disabled language falls back to it too.", "schema": { "type": [ "string", "null" ], "maxLength": 10 }, "example": "fr" }, { "name": "limit", "in": "query", "description": "Number of records per page, 1 to 100.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from `meta.next_cursor` (or `links.next`) of the previous page.", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "description": "Only records whose stored data changed at or after this moment (ISO 8601).\nResults are then ordered by `updated_at`, then `id`, so you can store the\nlast `updated_at` you saw and ask for everything since.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-01T00:00:00Z" }, { "name": "scope", "in": "query", "schema": { "$ref": "#\/components\/schemas\/TaskScope" } }, { "name": "type", "in": "query", "schema": { "$ref": "#\/components\/schemas\/TaskType" } } ], "responses": { "200": { "description": "Paginated set of `TaskResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/TaskResource" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/InvalidApiKey" }, "403": { "$ref": "#\/components\/responses\/WorkspaceSuspended" }, "422": { "$ref": "#\/components\/responses\/InvalidFilter" }, "429": { "$ref": "#\/components\/responses\/RateLimited" } } } }, "\/tasks\/{id}": { "get": { "operationId": "v1.tasks.show", "summary": "Get a task", "tags": [ "Tasks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The task's id, e.g. `task_Hq2LmVa8Kd`.", "schema": { "type": "string" } }, { "name": "lang", "in": "query", "description": "Language for translatable text (titles, descriptions, package and add-on names):\none of the workspace's enabled languages, e.g. `fr`. Defaults to the workspace's\ndefault language; an unknown or disabled language falls back to it too.", "schema": { "type": [ "string", "null" ], "maxLength": 10 }, "example": "fr" } ], "responses": { "200": { "description": "`TaskResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/TaskResource" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/InvalidApiKey" }, "403": { "$ref": "#\/components\/responses\/WorkspaceSuspended" }, "404": { "$ref": "#\/components\/responses\/NotFound" }, "422": { "$ref": "#\/components\/responses\/InvalidFilter" }, "429": { "$ref": "#\/components\/responses\/RateLimited" } } } }, "\/transactions": { "get": { "operationId": "v1.transactions.index", "description": "The money ledger: payments, refunds, store credit, disputes, write-offs and adjustments,\nfor finance reporting and reconciliation.", "summary": "List transactions", "tags": [ "Transactions" ], "parameters": [ { "name": "lang", "in": "query", "description": "Language for translatable text (titles, descriptions, package and add-on names):\none of the workspace's enabled languages, e.g. `fr`. Defaults to the workspace's\ndefault language; an unknown or disabled language falls back to it too.", "schema": { "type": [ "string", "null" ], "maxLength": 10 }, "example": "fr" }, { "name": "limit", "in": "query", "description": "Number of records per page, 1 to 100.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from `meta.next_cursor` (or `links.next`) of the previous page.", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "description": "Only records whose stored data changed at or after this moment (ISO 8601).\nResults are then ordered by `updated_at`, then `id`, so you can store the\nlast `updated_at` you saw and ask for everything since.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-01T00:00:00Z" }, { "name": "kind", "in": "query", "schema": { "$ref": "#\/components\/schemas\/TransactionKind" } }, { "name": "status", "in": "query", "schema": { "$ref": "#\/components\/schemas\/TransactionStatus" } }, { "name": "booking_id", "in": "query", "description": "Only transactions on this booking.", "schema": { "type": "string" }, "example": "bk_5odpWrSW5L" }, { "name": "customer_id", "in": "query", "description": "Only transactions of this customer.", "schema": { "type": "string" }, "example": "cus_MAmYDWY3Ku" }, { "name": "occurred_after", "in": "query", "description": "Only transactions that happened at or after this moment (ISO 8601).", "schema": { "type": "string", "format": "date-time" }, "example": "2026-09-01T00:00:00Z" }, { "name": "occurred_before", "in": "query", "description": "Only transactions that happened at or before this moment (ISO 8601).", "schema": { "type": "string", "format": "date-time" }, "example": "2026-09-30T23:59:59Z" } ], "responses": { "200": { "description": "Paginated set of `TransactionResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/TransactionResource" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/InvalidApiKey" }, "403": { "$ref": "#\/components\/responses\/WorkspaceSuspended" }, "422": { "$ref": "#\/components\/responses\/InvalidFilter" }, "429": { "$ref": "#\/components\/responses\/RateLimited" } } } }, "\/transactions\/{id}": { "get": { "operationId": "v1.transactions.show", "summary": "Get a transaction", "tags": [ "Transactions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The transaction's id, e.g. `txn_Q2mVb8LkXa`.", "schema": { "type": "string" } }, { "name": "lang", "in": "query", "description": "Language for translatable text (titles, descriptions, package and add-on names):\none of the workspace's enabled languages, e.g. `fr`. Defaults to the workspace's\ndefault language; an unknown or disabled language falls back to it too.", "schema": { "type": [ "string", "null" ], "maxLength": 10 }, "example": "fr" } ], "responses": { "200": { "description": "`TransactionResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/TransactionResource" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/InvalidApiKey" }, "403": { "$ref": "#\/components\/responses\/WorkspaceSuspended" }, "404": { "$ref": "#\/components\/responses\/NotFound" }, "422": { "$ref": "#\/components\/responses\/InvalidFilter" }, "429": { "$ref": "#\/components\/responses\/RateLimited" } } } }, "\/workspace": { "get": { "operationId": "v1.workspace", "description": "The workspace the API key belongs to. A cheap way to check a key works.", "summary": "Get the workspace", "tags": [ "Workspace" ], "parameters": [ { "name": "lang", "in": "query", "description": "Language for translatable text (titles, descriptions, package and add-on names):\none of the workspace's enabled languages, e.g. `fr`. Defaults to the workspace's\ndefault language; an unknown or disabled language falls back to it too.", "schema": { "type": [ "string", "null" ], "maxLength": 10 }, "example": "fr" } ], "responses": { "200": { "description": "`WorkspaceResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/WorkspaceResource" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/InvalidApiKey" }, "403": { "$ref": "#\/components\/responses\/WorkspaceSuspended" }, "422": { "$ref": "#\/components\/responses\/InvalidFilter" }, "429": { "$ref": "#\/components\/responses\/RateLimited" } } } } }, "components": { "securitySchemes": { "http": { "type": "http", "description": "A workspace API key (`smb_sk_\u2026`), created under Settings \u2192 API keys.", "scheme": "bearer" } }, "schemas": { "AddOnPricingUnit": { "type": "string", "enum": [ "per_booking", "per_participant" ], "title": "AddOnPricingUnit" }, "AddOnResource": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "examples": [ "addon_MsmdWY3Kue" ] }, "name": { "examples": [ "E-bike rental" ] }, "description": { "examples": [ "Pedal-assist bike for the whole trip." ] }, "price_amount": { "type": "integer", "description": "Price in minor units (cents), per booking or per participant (see `pricing_unit`).", "examples": [ 5000 ] }, "currency": { "type": "string", "examples": [ "EUR" ] }, "pricing_unit": { "examples": [ "per_participant" ], "$ref": "#\/components\/schemas\/AddOnPricingUnit" } }, "required": [ "id", "name", "description", "price_amount", "currency", "pricing_unit" ], "title": "AddOnResource" }, "BookingPaymentStatus": { "type": "string", "enum": [ "unpaid", "partially_paid", "paid", "overdue", "partially_refunded", "refunded" ], "title": "BookingPaymentStatus" }, "BookingRequestResource": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "examples": [ "breq_Lm3Vq8ZpTa" ] }, "reference": { "type": "string", "examples": [ "REQ-2026-000089" ] }, "status": { "examples": [ "pending" ], "$ref": "#\/components\/schemas\/BookingRequestStatus" }, "source": { "examples": [ "on_request" ], "$ref": "#\/components\/schemas\/BookingSource" }, "experience_id": { "type": [ "string", "null" ], "examples": [ "exp_eUSX7jbEV9" ] }, "package": { "type": [ "object", "null" ], "description": "Package requested, with its name as quoted.", "properties": { "id": { "type": [ "string", "null" ], "examples": [ "pkg_By7zeseTZW" ] }, "name": { "type": "string", "examples": [ "Standard" ] } }, "required": [ "id", "name" ] }, "proposed_start_at": { "type": "string", "examples": [ "2026-11-02T00:00:00Z" ] }, "proposed_start_time": { "type": [ "string", "null" ], "description": "Requested start time (`HH:MM`, workspace time), when the traveler picked one.", "examples": [ "09:30" ] }, "participant_count": { "type": "integer", "examples": [ 4 ] }, "lead": { "type": "object", "description": "Lead traveler as entered on the request. Null fields once the customer is anonymized.", "properties": { "first_name": { "examples": [ "Ada" ] }, "last_name": { "examples": [ "Lovelace" ] }, "email": { "examples": [ "ada@example.com" ] } }, "required": [ "first_name", "last_name", "email" ] }, "customer": { "type": [ "object", "null" ], "description": "Snapshot of the buyer for convenience; sync customers through `\/customers`.", "properties": { "id": { "type": [ "string", "null" ], "examples": [ "cus_MAmYDWY3Ku" ] }, "email": { "type": [ "string", "null" ], "examples": [ "emma.lindqvist@example.com" ] }, "first_name": { "type": [ "string", "null" ], "examples": [ "Emma" ] }, "last_name": { "type": [ "string", "null" ], "examples": [ "Lindqvist" ] }, "anonymized": { "type": "boolean", "examples": [ false ] } }, "required": [ "id", "email", "first_name", "last_name", "anonymized" ] }, "totals": { "type": "object", "description": "Quoted amounts, in minor units of `currency`.", "properties": { "subtotal_amount": { "type": [ "integer", "null" ], "examples": [ 245000 ] }, "add_ons_total_amount": { "type": [ "integer", "null" ], "examples": [ 0 ] }, "discount_amount": { "type": [ "integer", "null" ], "examples": [ 0 ] }, "vat_amount": { "type": [ "integer", "null" ], "examples": [ 0 ] }, "total_amount": { "type": [ "integer", "null" ], "examples": [ 245000 ] }, "deposit_amount": { "type": [ "integer", "null" ], "examples": [ 49000 ] }, "currency": { "examples": [ "EUR" ] } }, "required": [ "subtotal_amount", "add_ons_total_amount", "discount_amount", "vat_amount", "total_amount", "deposit_amount", "currency" ] }, "expires_at": { "type": "string", "examples": [ "2026-10-07T09:00:00Z" ] }, "decided_at": { "type": "string", "examples": [ null ] }, "rejection_reason": { "type": [ "string", "null" ], "examples": [ null ] }, "booking_id": { "type": [ "string", "null" ], "description": "The booking created when the request was accepted.", "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-10-05T09:00:00Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-10-05T09:00:00Z" ] } }, "required": [ "id", "reference", "status", "source", "experience_id", "package", "proposed_start_at", "proposed_start_time", "participant_count", "lead", "customer", "totals", "expires_at", "decided_at", "rejection_reason", "booking_id", "created_at", "updated_at" ], "title": "BookingRequestResource" }, "BookingRequestStatus": { "type": "string", "enum": [ "pending", "accepted", "rejected", "expired", "cancelled", "accepted_capture_failed" ], "title": "BookingRequestStatus" }, "BookingResource": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "examples": [ "bk_5odpWrSW5L" ] }, "reference": { "type": "string", "examples": [ "SMB-2026-000123" ] }, "status": { "examples": [ "confirmed" ], "$ref": "#\/components\/schemas\/BookingStatus" }, "payment_status": { "examples": [ "partially_paid" ], "$ref": "#\/components\/schemas\/BookingPaymentStatus" }, "source": { "examples": [ "public_checkout" ], "$ref": "#\/components\/schemas\/BookingSource" }, "experience_id": { "type": [ "string", "null" ], "examples": [ "exp_eUSX7jbEV9" ] }, "departure_id": { "type": [ "string", "null" ], "examples": [ "dep_SGbSQzmJVG" ] }, "package": { "type": [ "object", "null" ], "description": "Package booked (multi-day trips), with its name as sold.", "properties": { "id": { "type": [ "string", "null" ], "examples": [ "pkg_By7zeseTZW" ] }, "name": { "type": [ "string", "null" ], "examples": [ "Standard" ] } }, "required": [ "id", "name" ] }, "customer": { "type": [ "object", "null" ], "description": "Snapshot of the buyer for convenience. A customer edit does not change the\nbooking's `updated_at`: sync customers through `\/customers`.", "properties": { "id": { "type": [ "string", "null" ], "examples": [ "cus_MAmYDWY3Ku" ] }, "email": { "type": [ "string", "null" ], "examples": [ "emma.lindqvist@example.com" ] }, "first_name": { "type": [ "string", "null" ], "examples": [ "Emma" ] }, "last_name": { "type": [ "string", "null" ], "examples": [ "Lindqvist" ] }, "anonymized": { "type": "boolean", "examples": [ false ] } }, "required": [ "id", "email", "first_name", "last_name", "anonymized" ] }, "participant_count": { "type": "integer", "examples": [ 2 ] }, "subtotal_amount": { "type": "integer", "description": "All amounts are in minor units (cents) of `currency`.", "examples": [ 240000 ] }, "add_ons_total_amount": { "type": "integer", "examples": [ 10000 ] }, "discount_amount": { "type": "integer", "examples": [ 0 ] }, "vat_amount": { "type": "integer", "examples": [ 0 ] }, "fees_passed_amount": { "type": "integer", "description": "Samba fee passed on to the customer, included in `total_amount`.", "examples": [ 0 ] }, "total_amount": { "type": "integer", "examples": [ 250000 ] }, "paid_amount": { "type": "integer", "examples": [ 75000 ] }, "outstanding_amount": { "type": "integer", "examples": [ 175000 ] }, "currency": { "type": "string", "examples": [ "EUR" ] }, "participants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "passenger_type": { "type": [ "string", "null" ] }, "package": { "type": [ "string", "null" ] } }, "required": [ "id", "first_name", "last_name", "passenger_type", "package" ] } }, "add_ons": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "add_on_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "pricing_unit": { "type": "string" }, "quantity": { "type": "integer" }, "unit_amount": { "type": "integer" }, "total_amount": { "type": "integer" } }, "required": [ "id", "add_on_id", "name", "pricing_unit", "quantity", "unit_amount", "total_amount" ] } }, "payment_schedule": { "type": [ "object", "null" ], "description": "Deposit and instalments, when the booking is paid on a schedule.", "properties": { "status": { "examples": [ "active" ], "$ref": "#\/components\/schemas\/PaymentPlanStatus" }, "total_amount": { "type": "integer", "examples": [ 250000 ] }, "deposit_amount": { "type": "integer", "examples": [ 75000 ] }, "currency": { "type": "string", "examples": [ "EUR" ] }, "auto_billing": { "type": "boolean", "description": "Whether instalments are charged automatically on their due date.", "examples": [ true ] }, "installments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "due_on": { "type": "string" }, "amount": { "type": "integer" }, "status": { "$ref": "#\/components\/schemas\/InstallmentStatus" }, "paid_at": { "type": "string" } }, "required": [ "id", "due_on", "amount", "status", "paid_at" ] } } }, "required": [ "status", "total_amount", "deposit_amount", "currency", "auto_billing", "installments" ] }, "pickup": { "type": [ "object", "null" ], "description": "Pickup chosen at booking, as it was then.", "properties": { "pickup_point_id": { "type": [ "string", "null" ], "examples": [ "pick_Va8KdHq2Lm" ] }, "name": { "type": [ "string", "null" ], "examples": [ "Hotel Lobby" ] }, "address": { "type": [ "string", "null" ], "examples": [ "1 Main Street, Chamonix" ] }, "time_offset_minutes": { "type": [ "integer", "null" ], "description": "Minutes before the departure start: `30` means travelers are picked up 30\nminutes before it (08:30 for a 09:00 start).", "examples": [ 30 ] } }, "required": [ "pickup_point_id", "name", "address", "time_offset_minutes" ] }, "discount_code": { "type": [ "object", "null" ], "description": "Code applied at checkout. `code` is a snapshot.", "properties": { "id": { "type": [ "string", "null" ], "examples": [ "dsc_2LmVa8KdHq" ] }, "code": { "type": "string", "examples": [ "SUMMER26" ] } }, "required": [ "id", "code" ] }, "channel": { "type": [ "object", "null" ], "description": "The OTA that sold the booking, for bookings with `source: channel`.", "properties": { "name": { "type": "string", "const": "getyourguide", "examples": [ "getyourguide" ] }, "booking_reference": { "type": "string", "examples": [ "GYGABC123XY" ] } }, "required": [ "name", "booking_reference" ] }, "cancellation_policy": { "description": "Cancellation terms as sold, frozen at booking time. Null for bookings made before\nterms were recorded.", "anyOf": [ { "type": "object", "properties": { "non_refundable": { "type": "boolean" }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "days_before": { "type": "integer" }, "refund_percent": { "type": "integer" } }, "required": [ "days_before", "refund_percent" ] } } }, "required": [ "non_refundable", "tiers" ] }, { "type": "null" }, { "type": "object", "properties": { "non_refundable": { "type": "boolean" }, "tiers": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0 } }, "required": [ "non_refundable", "tiers" ] } ] }, "confirmed_at": { "type": "string", "examples": [ "2026-09-14T08:12:44Z" ] }, "cancelled_at": { "type": "string", "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-09-14T08:10:02Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-09-20T16:03:11Z" ] } }, "required": [ "id", "reference", "status", "payment_status", "source", "experience_id", "departure_id", "package", "customer", "participant_count", "subtotal_amount", "add_ons_total_amount", "discount_amount", "vat_amount", "fees_passed_amount", "total_amount", "paid_amount", "outstanding_amount", "currency", "participants", "add_ons", "payment_schedule", "pickup", "discount_code", "channel", "cancellation_policy", "confirmed_at", "cancelled_at", "created_at", "updated_at" ], "title": "BookingResource" }, "BookingSource": { "type": "string", "enum": [ "public_checkout", "operator_created", "widget", "on_request", "channel" ], "title": "BookingSource" }, "BookingStatus": { "type": "string", "enum": [ "pending", "confirmed", "cancelled", "refunded" ], "title": "BookingStatus" }, "CancellationRequestResolution": { "type": "string", "enum": [ "apply_policy", "custom_amount", "full_refund", "no_refund" ], "title": "CancellationRequestResolution" }, "CancellationRequestResource": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "examples": [ "creq_KdHq2LmVa8" ] }, "booking_id": { "type": [ "string", "null" ], "examples": [ "bk_5odpWrSW5L" ] }, "status": { "examples": [ "approved" ], "$ref": "#\/components\/schemas\/CancellationRequestStatus" }, "resolution": { "anyOf": [ { "description": "How it was settled: `apply_policy`, `custom_amount`, `full_refund` or `no_refund`.\nNull while pending.", "examples": [ "apply_policy" ], "$ref": "#\/components\/schemas\/CancellationRequestResolution" }, { "type": "null" } ] }, "reason_code": { "type": [ "string", "null" ], "examples": [ "illness" ] }, "traveler_reason": { "type": "string", "examples": [ "I broke my ankle and can't hike." ] }, "operator_message": { "type": [ "string", "null" ], "description": "The operator's reply, as sent to the traveler.", "examples": [ "Sorry to hear that, get well soon." ] }, "refund_requested_amount": { "type": [ "integer", "null" ], "examples": [ 60000 ] }, "refund_sent_amount": { "type": "integer", "description": "Refunded so far.", "examples": [ 60000 ] }, "policy_suggested_amount": { "type": [ "integer", "null" ], "description": "What the cancellation policy suggested when the request came in.", "examples": [ 60000 ] }, "currency": { "type": "string", "examples": [ "EUR" ] }, "policy_days_before": { "type": [ "integer", "null" ], "description": "Days before departure when the request came in.", "examples": [ 45 ] }, "requested_at": { "type": "string", "examples": [ "2026-09-14T08:12:44Z" ] }, "responded_at": { "type": "string", "examples": [ "2026-09-15T10:00:00Z" ] }, "created_at": { "type": "string", "examples": [ "2026-09-14T08:12:44Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-09-15T10:00:00Z" ] } }, "required": [ "id", "booking_id", "status", "resolution", "reason_code", "traveler_reason", "operator_message", "refund_requested_amount", "refund_sent_amount", "policy_suggested_amount", "currency", "policy_days_before", "requested_at", "responded_at", "created_at", "updated_at" ], "title": "CancellationRequestResource" }, "CancellationRequestStatus": { "type": "string", "enum": [ "pending", "approved", "denied" ], "title": "CancellationRequestStatus" }, "ContentBlockType": { "type": "string", "enum": [ "itinerary_day", "inclusions", "practical_info", "faq", "gallery", "highlights", "itinerary_map", "accommodation", "guides", "testimonial", "video", "stats_strip", "rich_text", "cancellation_policy", "post_booking_tasks" ], "title": "ContentBlockType" }, "CreditNoteKind": { "type": "string", "enum": [ "refund", "credit" ], "title": "CreditNoteKind" }, "CustomerResource": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "examples": [ "cus_MAmYDWY3Ku" ] }, "email": { "type": [ "string", "null" ], "examples": [ "emma.lindqvist@example.com" ] }, "first_name": { "type": [ "string", "null" ], "examples": [ "Emma" ] }, "last_name": { "type": [ "string", "null" ], "examples": [ "Lindqvist" ] }, "phone": { "type": [ "string", "null" ], "examples": [ "+46701234567" ] }, "company": { "type": [ "string", "null" ], "examples": [ null ] }, "address": { "type": "object", "properties": { "line1": { "type": [ "string", "null" ] }, "line2": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ], "examples": [ "Stockholm" ] }, "postal_code": { "type": [ "string", "null" ], "examples": [ "111 57" ] }, "region": { "type": [ "string", "null" ], "examples": [ null ] }, "country": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country code.", "examples": [ "SE" ] } }, "required": [ "line1", "line2", "city", "postal_code", "region", "country" ] }, "language": { "type": [ "string", "null" ], "description": "Preferred language for emails.", "examples": [ "en" ] }, "marketing_opt_in": { "type": "boolean", "examples": [ true ] }, "bookings_count": { "type": "integer", "description": "Number of confirmed bookings.", "examples": [ 3 ] }, "total_spent": { "type": "array", "description": "Total of confirmed bookings, one entry per currency, in minor units.", "examples": [ [ { "amount": 480000, "currency": "EUR" }, { "amount": 95000, "currency": "USD" } ] ], "items": { "type": "object", "properties": { "amount": { "type": "integer" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ] } }, "credit_balances": { "type": "array", "description": "Store credit available to spend, one entry per currency, in minor units.", "examples": [ [ { "currency": "EUR", "available_amount": 10000 } ] ], "items": { "type": "object", "properties": { "currency": { "type": "string" }, "available_amount": { "type": "integer" } }, "required": [ "currency", "available_amount" ] } }, "first_booking_at": { "type": "string", "examples": [ "2025-05-30T19:02:10Z" ] }, "last_booking_at": { "type": "string", "examples": [ "2026-09-14T08:12:44Z" ] }, "anonymized": { "type": "boolean", "description": "True once the customer was anonymized (GDPR); personal fields are then null.", "examples": [ false ] }, "created_at": { "type": "string", "examples": [ "2025-05-30T19:00:41Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-09-20T16:03:11Z" ] } }, "required": [ "id", "email", "first_name", "last_name", "phone", "company", "address", "language", "marketing_opt_in", "bookings_count", "total_spent", "credit_balances", "first_booking_at", "last_booking_at", "anonymized", "created_at", "updated_at" ], "title": "CustomerResource" }, "DepartureResource": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "examples": [ "dep_SGbSQzmJVG" ] }, "experience_id": { "type": "string", "examples": [ "exp_eUSX7jbEV9" ] }, "start_at": { "type": "string", "examples": [ "2027-07-04T06:00:00Z" ] }, "end_at": { "type": "string", "examples": [ "2027-07-14T15:00:00Z" ] }, "timezone": { "type": "string", "description": "IANA timezone of the workspace, for displaying `start_at`\/`end_at` locally.", "examples": [ "Europe\/Paris" ] }, "status": { "examples": [ "scheduled" ], "$ref": "#\/components\/schemas\/DepartureStatus" }, "capacity": { "type": "integer", "examples": [ 12 ] }, "seats_remaining": { "type": "integer", "description": "Seats still available: capacity minus confirmed bookings minus seats held in\ncheckouts in progress. Live field: it can change without `updated_at` moving\n(holds expire), so read it fresh rather than syncing it with `updated_since`.", "examples": [ 5 ] }, "bookable": { "type": "boolean", "description": "Whether a traveler can book it right now (scheduled, before the booking cutoff,\nseats left). Live field: flips with time, not covered by `updated_since`.", "examples": [ true ] }, "price_range": { "type": [ "object", "null" ], "description": "Advertised price range in minor units, null when the departure has no paid\nprice. Live field: date-based pricing steps switch it with time.", "examples": [ { "min_amount": 120000, "max_amount": 165000, "currency": "EUR" } ], "properties": { "min_amount": { "type": "integer" }, "max_amount": { "type": "integer" }, "currency": { "type": "string" } }, "required": [ "min_amount", "max_amount", "currency" ] }, "booking_url": { "type": [ "string", "null" ], "description": "Checkout for this departure. Null while the experience is a draft.", "examples": [ "https:\/\/book.sambahq.com\/alpine-adventures\/trips\/tour-du-mont-blanc\/checkout?departure=dep_SGbSQzmJVG" ] }, "created_at": { "type": "string", "examples": [ "2026-03-02T10:20:00Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-09-20T16:03:11Z" ] } }, "required": [ "id", "experience_id", "start_at", "end_at", "timezone", "status", "capacity", "seats_remaining", "bookable", "price_range", "booking_url", "created_at", "updated_at" ], "title": "DepartureResource" }, "DepartureStatus": { "type": "string", "enum": [ "scheduled", "sold_out", "cancelled" ], "title": "DepartureStatus" }, "DiscountCodeResource": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "examples": [ "dsc_2LmVa8KdHq" ] }, "code": { "type": "string", "examples": [ "SUMMER26" ] }, "scope": { "type": "string", "description": "`global`: every experience. `experience`: only `experience_id`.", "examples": [ "global" ] }, "experience_id": { "type": [ "string", "null" ], "examples": [ null ] }, "type": { "type": "string", "examples": [ "percent" ] }, "percent_off": { "type": [ "number", "null" ], "description": "Percentage off for `percent` codes, e.g. `12.5`. Null for `fixed` codes.", "examples": [ 12.5 ] }, "amount_off": { "type": [ "integer", "null" ], "description": "Amount off for `fixed` codes, in minor units of the booking's currency: a code\ncarries no currency, and checkout takes the same number off a EUR or a USD cart.\nNull for `percent` codes.", "examples": [ null ] }, "max_redemptions": { "type": [ "integer", "null" ], "examples": [ 100 ] }, "redemptions_count": { "type": "integer", "examples": [ 3 ] }, "min_booking_amount": { "type": [ "integer", "null" ], "description": "Minimum booking subtotal, in minor units of the booking's currency (see `amount_off`).", "examples": [ 20000 ] }, "starts_at": { "type": "string", "examples": [ null ] }, "expires_at": { "type": "string", "examples": [ "2026-12-31T23:59:59Z" ] }, "archived_at": { "type": "string", "examples": [ null ] }, "departure_ids": { "type": [ "array", "null" ], "description": "Departures the code is limited to; null when it is not limited to departures.", "examples": [ null ], "items": { "type": "string" } }, "status": { "description": "Live field, evaluated at request time: it changes as dates pass without moving\n`updated_at`. Derive it yourself from `starts_at`, `expires_at`,\n`max_redemptions` and `archived_at` if you cache codes.", "examples": [ "active" ], "$ref": "#\/components\/schemas\/DiscountCodeStatus" }, "created_at": { "type": "string", "examples": [ "2026-05-01T08:00:00Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-09-14T08:12:44Z" ] } }, "required": [ "id", "code", "scope", "experience_id", "type", "percent_off", "amount_off", "max_redemptions", "redemptions_count", "min_booking_amount", "starts_at", "expires_at", "archived_at", "departure_ids", "status", "created_at", "updated_at" ], "title": "DiscountCodeResource" }, "DiscountCodeStatus": { "type": "string", "description": "Lifecycle state of a DiscountCode, derived from the persisted fields (`archived_at`, `starts_at`, `expires_at`, `max_redemptions`, `redemptions_count`). The enum is presentation-only \u2014 the validator in app\/Services\/Discounts\/DiscountCodeValidator.php is still the source of truth for \"is this code honorable right now?\" \u2014 but the cases share semantics so labels and filters read the same.\n", "enum": [ "active", "future", "expired", "archived" ], "title": "DiscountCodeStatus" }, "ExperienceDifficulty": { "type": "string", "enum": [ "easy", "moderate", "hard", "expert" ], "title": "ExperienceDifficulty" }, "ExperienceResource": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "examples": [ "exp_eUSX7jbEV9" ] }, "slug": { "type": "string", "examples": [ "tour-du-mont-blanc" ] }, "title": { "examples": [ "Tour du Mont Blanc" ] }, "description": { "description": "Long description as authored in the editor (may contain HTML).", "examples": [ "

Eleven days around the Mont Blanc massif through France, Italy and Switzerland.<\/p>" ] }, "status": { "examples": [ "published" ], "$ref": "#\/components\/schemas\/ExperienceStatus" }, "type": { "examples": [ "multi_day" ], "$ref": "#\/components\/schemas\/ExperienceType" }, "duration_minutes": { "type": "integer", "examples": [ 15840 ] }, "difficulty": { "anyOf": [ { "examples": [ "moderate" ], "$ref": "#\/components\/schemas\/ExperienceDifficulty" }, { "type": "null" } ] }, "cover_image_url": { "type": [ "string", "null" ], "examples": [ "https:\/\/files.sambahq.com\/covers\/tour-du-mont-blanc.jpg" ] }, "booking_url": { "type": [ "string", "null" ], "description": "Public trip page. Null while the experience is a draft.", "examples": [ "https:\/\/book.sambahq.com\/alpine-adventures\/trips\/tour-du-mont-blanc" ] }, "archived_at": { "type": "string", "examples": [ null ] }, "packages": { "type": "array", "description": "Packages a traveler picks from (multi-day trips).", "items": { "$ref": "#\/components\/schemas\/PriceOptionResource" } }, "passenger_types": { "type": "array", "description": "Passenger types a traveler picks from (day tours).", "items": { "$ref": "#\/components\/schemas\/PriceOptionResource" } }, "add_ons": { "type": "array", "items": { "$ref": "#\/components\/schemas\/AddOnResource" } }, "pickup_points": { "type": "array", "description": "Where travelers can be picked up, in display order. `time_offset_minutes` is\nminutes before the departure start: `30` means 08:30 for a 09:00 start.", "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "name": {}, "address": {}, "latitude": { "type": [ "number", "null" ] }, "longitude": { "type": [ "number", "null" ] }, "time_offset_minutes": { "type": "integer" } }, "required": [ "id", "name", "address", "latitude", "longitude", "time_offset_minutes" ] } }, "cancellation_policy": { "description": "The cancellation policy new bookings get: the experience's own, else your workspace\ndefault. Null when neither exists.", "anyOf": [ { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "name": {}, "non_refundable": { "type": "boolean" }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "days_before": { "type": "integer" }, "refund_percent": { "type": "integer" } }, "required": [ "days_before", "refund_percent" ] } }, "text": {} }, "required": [ "id", "name", "non_refundable", "tiers", "text" ] }, { "type": "null" }, { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" }, "non_refundable": { "type": "boolean" }, "tiers": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0 }, "text": { "type": "null" } }, "required": [ "id", "name", "non_refundable", "tiers", "text" ] } ] }, "folders": { "type": "array", "description": "Folders the experience is listed in on your trips page and widget.", "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "name": {}, "slug": { "type": "string" }, "description": {}, "cover_image_url": { "type": [ "string", "null" ] }, "position": { "type": "integer" } }, "required": [ "id", "name", "slug", "description", "cover_image_url", "position" ] } }, "content_blocks": { "type": "array", "description": "The trip page's content sections in order. `data` depends on `type`; fields are\nonly ever added to a type, never removed. Image fields are public URLs.", "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "type": { "$ref": "#\/components\/schemas\/ContentBlockType" }, "position": { "type": "integer" }, "data": { "anyOf": [ { "type": "array" }, { "type": "object", "additionalProperties": {} } ] } }, "required": [ "id", "type", "position", "data" ] } }, "created_at": { "type": "string", "examples": [ "2026-03-02T10:15:00Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-09-18T07:41:22Z" ] } }, "required": [ "id", "slug", "title", "description", "status", "type", "duration_minutes", "difficulty", "cover_image_url", "booking_url", "archived_at", "packages", "passenger_types", "add_ons", "pickup_points", "cancellation_policy", "folders", "content_blocks", "created_at", "updated_at" ], "title": "ExperienceResource" }, "ExperienceStatus": { "type": "string", "enum": [ "draft", "published" ], "title": "ExperienceStatus" }, "ExperienceType": { "type": "string", "enum": [ "multi_day", "day_tour" ], "title": "ExperienceType" }, "InstallmentStatus": { "type": "string", "enum": [ "scheduled", "paid", "failed", "refunded", "cancelled" ], "title": "InstallmentStatus" }, "InvoiceKind": { "type": "string", "enum": [ "invoice", "credit_note" ], "title": "InvoiceKind" }, "InvoiceResource": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "examples": [ "inv_8KdPq2LmVa" ] }, "number": { "type": "string", "examples": [ "INV-2026-000042" ] }, "kind": { "examples": [ "invoice" ], "$ref": "#\/components\/schemas\/InvoiceKind" }, "credit_note_kind": { "anyOf": [ { "description": "For credit notes: `refund` (money returned) or `credit` (store credit). Null on invoices.", "examples": [ null ], "$ref": "#\/components\/schemas\/CreditNoteKind" }, { "type": "null" } ] }, "status": { "examples": [ "partially_paid" ], "$ref": "#\/components\/schemas\/InvoiceStatus" }, "issued_at": { "type": "string", "examples": [ "2026-09-14T08:12:44Z" ] }, "due_at": { "type": "string", "examples": [ null ] }, "booking_id": { "type": [ "string", "null" ], "examples": [ "bk_5odpWrSW5L" ] }, "credit_note_for": { "type": [ "string", "null" ], "description": "For a credit note, the invoice it reverses.", "examples": [ null ] }, "buyer": { "type": "object", "description": "The buyer as printed on the document.", "properties": { "first_name": { "type": [ "string", "null" ], "examples": [ "Emma" ] }, "last_name": { "type": [ "string", "null" ], "examples": [ "Lindqvist" ] }, "email": { "type": [ "string", "null" ], "examples": [ "emma.lindqvist@example.com" ] }, "phone": { "type": [ "string", "null" ], "examples": [ "+46701234567" ] }, "address": { "type": [ "object", "null" ], "properties": { "line1": { "type": [ "string", "null" ] }, "line2": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] } }, "required": [ "line1", "line2", "city", "postal_code", "region", "country" ] } }, "required": [ "first_name", "last_name", "email", "phone", "address" ] }, "seller": { "type": "object", "description": "Your business as printed on the document.", "properties": { "legal_name": { "type": [ "string", "null" ], "examples": [ "Alpine Adventures SAS" ] }, "vat_number": { "type": [ "string", "null" ], "examples": [ "FR12345678901" ] }, "address": { "type": [ "object", "null" ], "properties": { "line1": { "type": [ "string", "null" ] }, "line2": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] } }, "required": [ "line1", "line2", "city", "postal_code", "region", "country" ] } }, "required": [ "legal_name", "vat_number", "address" ] }, "lines": { "type": "array", "description": "Net amounts per line in minor units; discount and credit-note lines are negative.", "examples": [ [ { "label": "Tour du Mont Blanc", "amount": 100000, "vat_rate_bps": 2000 } ] ], "items": { "type": "object", "properties": { "label": { "type": "string" }, "amount": { "type": "integer" }, "vat_rate_bps": { "type": "integer" } }, "required": [ "label", "amount", "vat_rate_bps" ] } }, "subtotal_amount": { "type": "integer", "examples": [ 95000 ] }, "vat_amount": { "type": "integer", "examples": [ 19000 ] }, "total_amount": { "type": "integer", "examples": [ 114000 ] }, "paid_amount": { "type": "integer", "examples": [ 50000 ] }, "currency": { "type": "string", "examples": [ "EUR" ] }, "payments": { "type": "array", "description": "Transactions applied to this document.", "items": { "type": "object", "properties": { "transaction_id": { "type": [ "string", "null" ] }, "amount": { "type": "integer" }, "applied_at": { "type": "string" } }, "required": [ "transaction_id", "amount", "applied_at" ] } }, "pdf_url": { "type": "string", "description": "The PDF. Download it with the same `Authorization: Bearer` header.", "examples": [ "https:\/\/api.sambahq.com\/v1\/invoices\/inv_8KdPq2LmVa\/pdf" ] }, "created_at": { "type": "string", "examples": [ "2026-09-14T08:12:44Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-09-20T16:03:11Z" ] } }, "required": [ "id", "number", "kind", "credit_note_kind", "status", "issued_at", "due_at", "booking_id", "credit_note_for", "buyer", "seller", "lines", "subtotal_amount", "vat_amount", "total_amount", "paid_amount", "currency", "payments", "pdf_url", "created_at", "updated_at" ], "title": "InvoiceResource" }, "InvoiceStatus": { "type": "string", "enum": [ "draft", "open", "partially_paid", "paid", "void" ], "title": "InvoiceStatus" }, "PaymentPlanStatus": { "type": "string", "enum": [ "active", "completed", "cancelled", "failed" ], "title": "PaymentPlanStatus" }, "PriceOptionResource": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "examples": [ "pkg_By7zeseTZW" ] }, "name": { "examples": [ "Standard" ] }, "description": { "examples": [ "Mountain huts and guesthouses, half board." ] }, "price_amount": { "type": "integer", "description": "Catalogue price in minor units (cents). Departures can override it, see `price_range` on departures.", "examples": [ 120000 ] }, "currency": { "type": "string", "examples": [ "EUR" ] } }, "required": [ "id", "name", "description", "price_amount", "currency" ], "title": "PriceOptionResource" }, "TaskAnswerResource": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "examples": [ "tans_Va8KdHq2Lm" ] }, "task": { "type": "object", "description": "Snapshot of the task for convenience; `\/tasks` is the source of truth. Editing a\ntask does not change its answers' `updated_at`.", "properties": { "id": { "type": [ "string", "null" ], "examples": [ "task_Hq2LmVa8Kd" ] }, "label": { "examples": [ "Passport expiry date" ] }, "type": { "examples": [ "date" ], "$ref": "#\/components\/schemas\/TaskType" } }, "required": [ "id", "label", "type" ] }, "respondent": { "type": "object", "description": "Who answered: a participant, or the booking itself for buyer-level tasks.", "properties": { "type": { "type": "string", "enum": [ "participant", "booking" ], "examples": [ "participant" ] }, "id": { "type": [ "string", "null" ], "examples": [ "par_2LmVa8KdHq" ] } }, "required": [ "type", "id" ] }, "booking_id": { "type": [ "string", "null" ], "examples": [ "bk_5odpWrSW5L" ] }, "value": { "description": "The answer, typed by the task's type: bool for `boolean` and `checkbox`, number\nfor `number`, `YYYY-MM-DD` for `date`, string for text and `select`, null for\n`file` (see `file`) and when unanswered. May contain sensitive personal data.", "examples": [ "2031-05-01" ], "type": [ "string", "null", "boolean", "number" ] }, "file": { "type": [ "object", "null" ], "description": "The uploaded file for `file` tasks. Download it with the same\n`Authorization: Bearer` header.", "properties": { "name": { "type": "string", "examples": [ "passport.pdf" ] }, "url": { "type": "string", "examples": [ "https:\/\/api.sambahq.com\/v1\/task-answers\/tans_Va8KdHq2Lm\/file" ] } }, "required": [ "name", "url" ] }, "completed_at": { "type": "string", "examples": [ "2026-09-20T16:03:11Z" ] }, "created_at": { "type": "string", "examples": [ "2026-09-14T08:12:44Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-09-20T16:03:11Z" ] } }, "required": [ "id", "task", "respondent", "booking_id", "value", "file", "completed_at", "created_at", "updated_at" ], "title": "TaskAnswerResource" }, "TaskResource": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "examples": [ "task_Hq2LmVa8Kd" ] }, "label": { "examples": [ "Passport number" ] }, "description": { "examples": [ "As printed on the passport you will travel with." ] }, "type": { "examples": [ "short_text" ], "$ref": "#\/components\/schemas\/TaskType" }, "options": { "type": [ "array", "null" ], "description": "Choices for `select` tasks. Null otherwise.", "examples": [ null ], "items": { "type": "string" } }, "scope": { "description": "`participant`: answered once per traveler. `buyer`: once per booking.", "examples": [ "participant" ], "$ref": "#\/components\/schemas\/TaskScope" }, "timing": { "description": "`booking`: asked at checkout. `pre_departure`: asked after booking, before the trip.", "examples": [ "pre_departure" ], "$ref": "#\/components\/schemas\/TaskTiming" }, "required": { "type": "boolean", "examples": [ true ] }, "due_days_before_departure": { "type": [ "integer", "null" ], "examples": [ 14 ] }, "archived_at": { "type": "string", "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-03-02T10:15:00Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-09-18T07:41:22Z" ] } }, "required": [ "id", "label", "description", "type", "options", "scope", "timing", "required", "due_days_before_departure", "archived_at", "created_at", "updated_at" ], "title": "TaskResource" }, "TaskScope": { "type": "string", "enum": [ "participant", "buyer" ], "title": "TaskScope" }, "TaskTiming": { "type": "string", "enum": [ "booking", "pre_departure" ], "title": "TaskTiming" }, "TaskType": { "type": "string", "enum": [ "short_text", "long_text", "date", "file", "select", "boolean", "number", "checkbox" ], "title": "TaskType" }, "TransactionGateway": { "type": "string", "enum": [ "stripe", "manual", "internal", "channel" ], "title": "TransactionGateway" }, "TransactionKind": { "type": "string", "enum": [ "payment", "refund", "credit_grant", "credit_apply", "dispute", "write_off", "adjustment" ], "title": "TransactionKind" }, "TransactionResource": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "examples": [ "txn_Q2mVb8LkXa" ] }, "kind": { "description": "What moved: a payment in, a refund out, store credit granted or used, a dispute,\na write-off or a manual adjustment.", "examples": [ "payment" ], "$ref": "#\/components\/schemas\/TransactionKind" }, "status": { "examples": [ "succeeded" ], "$ref": "#\/components\/schemas\/TransactionStatus" }, "amount": { "type": "integer", "description": "Always positive, in minor units of `currency`; `kind` gives the direction.", "examples": [ 75000 ] }, "currency": { "type": "string", "examples": [ "EUR" ] }, "gateway": { "examples": [ "stripe" ], "$ref": "#\/components\/schemas\/TransactionGateway" }, "payment_method": { "type": [ "string", "null" ], "description": "How a Stripe payment was made: `card`, `apple_pay`, `google_pay`, `klarna`, \u2026\nNull for other gateways and kinds.", "examples": [ "apple_pay" ] }, "booking_id": { "type": [ "string", "null" ], "examples": [ "bk_5odpWrSW5L" ] }, "customer_id": { "type": [ "string", "null" ], "examples": [ "cus_MAmYDWY3Ku" ] }, "related_transaction_id": { "type": [ "string", "null" ], "description": "For a refund, the payment it refunds.", "examples": [ null ] }, "installment_id": { "type": [ "string", "null" ], "description": "The payment-schedule instalment this payment settled.", "examples": [ "inst_7hTq2ZpLmA" ] }, "refunded_amount": { "type": [ "string", "null" ], "description": "Succeeded refunds against this payment. Null for other kinds.", "examples": [ "12000" ] }, "occurred_at": { "type": "string", "examples": [ "2026-09-14T08:12:44Z" ] }, "created_at": { "type": "string", "examples": [ "2026-09-14T08:12:45Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-09-14T08:12:45Z" ] } }, "required": [ "id", "kind", "status", "amount", "currency", "gateway", "payment_method", "booking_id", "customer_id", "related_transaction_id", "installment_id", "refunded_amount", "occurred_at", "created_at", "updated_at" ], "title": "TransactionResource" }, "TransactionStatus": { "type": "string", "enum": [ "pending", "succeeded", "failed", "voided" ], "title": "TransactionStatus" }, "WorkspaceResource": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "examples": [ "ws_5XdpSW5Lqo" ] }, "name": { "type": "string", "examples": [ "Alpine Adventures" ] }, "slug": { "type": "string", "examples": [ "alpine-adventures" ] }, "currency": { "type": "string", "description": "ISO 4217 currency code new prices are created in.", "examples": [ "EUR" ] }, "timezone": { "type": "string", "description": "IANA timezone departures are scheduled in.", "examples": [ "Europe\/Paris" ] }, "default_language": { "type": "string", "description": "Language operator content is written in; translatable fields default to it.", "examples": [ "en" ] }, "enabled_languages": { "type": "array", "description": "Languages accepted by `?lang=`. array_intersect preserves the order of its first argument, so\nthis both drops anything outside SupportedLocales::ALL (subset\ninvariant) and orders the result by SupportedLocales order.", "examples": [ [ "en", "fr", "de" ] ], "items": { "type": "string" } } }, "required": [ "id", "name", "slug", "currency", "timezone", "default_language", "enabled_languages" ], "title": "WorkspaceResource" } }, "responses": { "InvalidApiKey": { "description": "The `Authorization` header is missing, or the key is unknown or revoked.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "examples": [ "authentication_error" ] }, "code": { "type": "string", "examples": [ "invalid_api_key" ] }, "message": { "type": "string", "examples": [ "Missing or invalid API key. Send it as `Authorization: Bearer smb_sk_\u2026`." ] } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "WorkspaceSuspended": { "description": "The workspace the key belongs to is suspended.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "examples": [ "permission_error" ] }, "code": { "type": "string", "examples": [ "workspace_suspended" ] }, "message": { "type": "string", "examples": [ "This workspace has been suspended." ] } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "NotFound": { "description": "No record with this id in the key's workspace.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "examples": [ "invalid_request" ] }, "code": { "type": "string", "examples": [ "not_found" ] }, "message": { "type": "string", "examples": [ "The requested resource does not exist." ] } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "InvalidFilter": { "description": "A query parameter failed validation; `errors` lists the messages per parameter.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "examples": [ "invalid_request" ] }, "code": { "type": "string", "examples": [ "invalid_filter" ] }, "message": { "type": "string", "examples": [ "The selected status is invalid." ] }, "errors": { "type": "object", "examples": [ { "status": [ "The selected status is invalid." ] } ], "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "RateLimited": { "description": "More than 120 requests in a minute with this key. Wait for `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "examples": [ "rate_limit_error" ] }, "code": { "type": "string", "examples": [ "rate_limited" ] }, "message": { "type": "string", "examples": [ "Too many requests. Retry after the number of seconds in the Retry-After header." ] } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } } } } }