Skip to content
Quikstik Developers

Create booking intent

POST
/booking-intents
curl --request POST \
  --url https://quikstik-core.fly.dev/booking-intents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-tenant-id: 2489E9AD-2EE2-8E00-8EC9-32D5F69181C0' \
  --data '{ "offering_variant_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "start_time": "example", "duration_minutes": 1, "quantity": 1, "group_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "participants": [ { "participant_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "display_name": "example", "birth_date": "example" } ], "payer_hints": [ { "payer_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "covers_participant_ids": [ "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" ] } ], "affiliate_attribution": { "kind": "example", "affiliate_id": "example", "referral_code": "example", "campaign": "example" }, "seller_tenant_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "fulfilling_tenant_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "add_on_selections": [ { "add_on_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "quantity": 1 } ] }'

Captures a booking intent. This is not a booking execution API.

The intent object is designed to remain compatible with:

  • deposits + balances due later (payment obligations are vocabulary only here)
  • split payments / multiple payers
  • operational groups independent of billing
  • cross-tenant marketplace commerce (seller vs fulfilling tenant)

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
x-tenant-id
required
string format: uuid

Tenant identifier (UUID).

Authn/authz semantics are intentionally TBD for this contract slice; this header exists to keep the contract explicitly multi-tenant from day 0.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
offering_variant_id
required
string format: uuid
start_time

Start time (RFC3339) for slot-based offerings (TBD).

string
nullable
duration_minutes

Requested duration for duration-based rentals (TBD).

integer
nullable >= 1
quantity

Requested quantity (participants/items); semantics TBD.

integer
nullable >= 1
group_id

Optional operational group linkage (non-billing).

string format: uuid
nullable
participants
Array<object>
nullable
object
participant_id
required

Participant identifier (stable within commerce). Creation/identity semantics are TBD.

string format: uuid
display_name
string
nullable
birth_date

Birth date (YYYY-MM-DD). Optional; semantics TBD.

string
nullable
payer_hints

Vocabulary direction for split payments. This is not a payment execution surface.

Array<object>
nullable
object
payer_id
required

Payer identifier (vocabulary only; does not imply payment execution).

string format: uuid
covers_participant_ids

Optional linkage for “payer covers subset of participants” (vocabulary only).

Array<string>
nullable
affiliate_attribution
object
kind
required

Attribution kind (vocabulary only; semantics TBD).

string
affiliate_id

Affiliate identifier (TBD).

string
nullable
referral_code
string
nullable
campaign
string
nullable
seller_tenant_id

Marketplace vocabulary: the tenant that sells the booking (TBD).

string format: uuid
nullable
fulfilling_tenant_id

Marketplace vocabulary: the tenant that fulfills the booking (TBD).

string format: uuid
nullable
add_on_selections
Array<object>
nullable
object
add_on_id
required
string format: uuid
quantity
required
integer
>= 1

Example generated

{
  "offering_variant_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "start_time": "example",
  "duration_minutes": 1,
  "quantity": 1,
  "group_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "participants": [
    {
      "participant_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "display_name": "example",
      "birth_date": "example"
    }
  ],
  "payer_hints": [
    {
      "payer_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "covers_participant_ids": [
        "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"
      ]
    }
  ],
  "affiliate_attribution": {
    "kind": "example",
    "affiliate_id": "example",
    "referral_code": "example",
    "campaign": "example"
  },
  "seller_tenant_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "fulfilling_tenant_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "add_on_selections": [
    {
      "add_on_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "quantity": 1
    }
  ]
}

Responses

Section titled “Responses”

201

Section titled “201”

Booking intent created

Media typeapplication/json
object
booking_intent_id
required
string format: uuid
offering_variant_id
required
string format: uuid
departure_id

The departure (capacity leaf,) this hold bound to at creation, resolved server-side from (tenant, offering_variant_id, start_time). The purchase leg commits this leaf directly. Null only for an unscheduled hold (no start_time).

string format: uuid
nullable
created_at_ms
required

Unix epoch milliseconds.

integer format: int64
status
required

Intent status (vocabulary only). This contract slice does not define lifecycle execution. Examples: created, cancel_requested.

string
start_time
string
nullable
duration_minutes
integer
nullable
quantity
integer
nullable
group_id
string format: uuid
nullable
participants
Array<object>
nullable
object
participant_id
required

Participant identifier (stable within commerce). Creation/identity semantics are TBD.

string format: uuid
display_name
string
nullable
birth_date

Birth date (YYYY-MM-DD). Optional; semantics TBD.

string
nullable
payer_hints
Array<object>
nullable
object
payer_id
required

Payer identifier (vocabulary only; does not imply payment execution).

string format: uuid
covers_participant_ids

Optional linkage for “payer covers subset of participants” (vocabulary only).

Array<string>
nullable
affiliate_attribution
object
kind
required

Attribution kind (vocabulary only; semantics TBD).

string
affiliate_id

Affiliate identifier (TBD).

string
nullable
referral_code
string
nullable
campaign
string
nullable
seller_tenant_id
string format: uuid
nullable
fulfilling_tenant_id
string format: uuid
nullable
add_on_selections
Array<object>
nullable
object
add_on_id
required
string format: uuid
quantity
required
integer
>= 1

Example generated

{
  "booking_intent_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "offering_variant_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "departure_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "created_at_ms": 1,
  "status": "example",
  "start_time": "example",
  "duration_minutes": 1,
  "quantity": 1,
  "group_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "participants": [
    {
      "participant_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "display_name": "example",
      "birth_date": "example"
    }
  ],
  "payer_hints": [
    {
      "payer_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "covers_participant_ids": [
        "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"
      ]
    }
  ],
  "affiliate_attribution": {
    "kind": "example",
    "affiliate_id": "example",
    "referral_code": "example",
    "campaign": "example"
  },
  "seller_tenant_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "fulfilling_tenant_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "add_on_selections": [
    {
      "add_on_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "quantity": 1
    }
  ]
}