Travel.Stays.Bookings (travel v0.2.0)

Copy Markdown View Source

Create, retrieve, list, and cancel bookings.

Endpoints

  • POST /stays/bookings - Create a booking
  • GET /stays/bookings/{id} - Get a booking
  • GET /stays/bookings - List bookings
  • PATCH /stays/bookings/{id} - Update a booking
  • POST /stays/bookings/{id}/actions/cancel - Cancel a booking

Examples

# Create a booking
{:ok, response} = Travel.Stays.Bookings.create(%{
  quote_id: "quo_123",
  guests: [%{given_name: "John", family_name: "Smith"}],
  email: "john@example.com",
  phone_number: "+447700900000"
})

# Get a booking
{:ok, response} = Travel.Stays.Bookings.get("bok_123")

# List bookings
{:ok, response} = Travel.Stays.Bookings.list(%{limit: 20})

# Cancel a booking
{:ok, response} = Travel.Stays.Bookings.cancel("bok_123")

@link https://duffel.com/docs/api/stays/bookings

Summary

Functions

cancel(booking_id)

Cancel a booking.

create(params)

Create a booking.

get(booking_id)

Get a booking by ID.

list(opts \\ nil)

List bookings with optional filtering and pagination.

stream(opts \\ nil)

List all bookings as a stream, handling pagination automatically.

update(booking_id, params)

Update a booking.

Functions

cancel(booking_id)

@spec cancel(String.t()) ::
  {:ok, Travel.Types.DuffelResponse.t()} | {:error, Travel.Error.t() | term()}

Cancel a booking.

Parameters

  • booking_id - The booking ID to cancel

Returns

  • {:ok, %Travel.Types.DuffelResponse{data: %Types.StaysBooking{}}} on success
  • {:error, %Travel.Error{}} on failure

create(params)

@spec create(map()) ::
  {:ok, Travel.Types.DuffelResponse.t()} | {:error, Travel.Error.t() | term()}

Create a booking.

Parameters

  • params - Booking parameters:
    • :quote_id - (required) The quote ID to book
    • :guests - (required) List of guests with given_name and family_name
    • :email - (required) Lead guest email
    • :phone_number - (required) Lead guest phone number
    • :loyalty_programme_account_number - (optional) Loyalty account number
    • :accommodation_special_requests - (optional) Special requests
    • :payment - (optional) Payment info
    • :metadata - (optional) Custom metadata map
    • :users - (optional) List of user IDs allowed to manage the booking

Returns

  • {:ok, %Travel.Types.DuffelResponse{data: %Types.StaysBooking{}}} on success
  • {:error, %Travel.Error{}} on failure

get(booking_id)

@spec get(String.t()) ::
  {:ok, Travel.Types.DuffelResponse.t()} | {:error, Travel.Error.t() | term()}

Get a booking by ID.

Parameters

  • booking_id - The booking ID

Returns

  • {:ok, %Travel.Types.DuffelResponse{data: %Types.StaysBooking{}}} on success
  • {:error, %Travel.Error{}} on failure

list(opts \\ nil)

@spec list(map() | nil) ::
  {:ok, Travel.Types.DuffelResponse.t()} | {:error, Travel.Error.t() | term()}

List bookings with optional filtering and pagination.

Parameters

  • opts - Optional query parameters:
    • :limit - Results per page (max 200)
    • :before - Cursor for previous page
    • :after - Cursor for next page
    • :user_id - Filter by customer user ID

Returns

  • {:ok, %Travel.Types.DuffelResponse{data: [%Types.StaysBooking{}]}} on success
  • {:error, %Travel.Error{}} on failure

stream(opts \\ nil)

@spec stream(map() | nil) :: Enumerable.t()

List all bookings as a stream, handling pagination automatically.

Parameters

  • opts - Optional query parameters (e.g., user_id)

Returns

A Stream that yields %Travel.Types.DuffelResponse{} for each page.

update(booking_id, params)

@spec update(String.t(), map()) ::
  {:ok, Travel.Types.DuffelResponse.t()} | {:error, Travel.Error.t() | term()}

Update a booking.

Parameters

  • booking_id - The booking ID
  • params - Update parameters:
    • :users - (required) List of user IDs allowed to manage the booking

Returns

  • {:ok, %Travel.Types.DuffelResponse{data: %Types.StaysBooking{}}} on success
  • {:error, %Travel.Error{}} on failure